canopycms 0.0.67-int.90 → 0.0.67

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

@@ -1,40 +1,32 @@
 /**
- * Branch-name sanitization, isolated in a dependency-free module.
+ * Branch-name sanitization, isolated in a dependency-free module (imports
+ * nothing but types; same pattern as assets/asset-prefixes.ts).
  *
- * Deliberately imports nothing but types: `paths/branch.ts` (the path
- * RESOLUTION module) pulls `node:fs` and the operating-mode strategies, so
- * isomorphic/client-reachable code (e.g. authorization/protected-branch.ts,
- * which the editor bundle reaches via api/guards.ts) must get
- * `sanitizeBranchName` from HERE, never from `paths/branch.ts` — a `node:`
- * import in that graph breaks adopters' production `next build` of the
- * editor bundle. Same pattern as assets/asset-prefixes.ts.
+ * Client-reachable code (e.g. authorization/protected-branch.ts, which the
+ * editor bundle reaches via api/guards.ts) MUST import `sanitizeBranchName`
+ * from HERE, never from `paths/branch.ts` or the `paths` barrel: both pull
+ * `node:fs` and the operating-mode strategies, and a `node:` import in that
+ * graph breaks adopters' production `next build` of the editor bundle.
+ * `pnpm lint:bundle` enforces it.
  */
 import type { SanitizedBranchName } from './types.js';
-/**
- * Sanitize a branch name for use in filesystem paths.
- * - Replaces invalid characters with hyphens
- * - Collapses multiple hyphens
- * - Trims leading/trailing dots
- */
+/** Sanitize a branch name for use in filesystem paths. */
 export declare function sanitizeBranchName(branchName: string): SanitizedBranchName;
 /**
- * Prefix reserved for CanopyCMS settings branches (`canopycms-settings-{name}`,
- * see operating-mode/client-unsafe-strategy.ts's `getSettingsBranchName` and
- * operating-mode/deployment-name.ts's `resolveDeploymentName`). Exported from
- * this dependency-free module -- not constructed ad hoc at each call site --
- * so every consumer that needs to recognize the settings-branch namespace
- * agrees on the exact string: worker/git-sync.ts's `pushSettingsBranches`
- * (never push a `canopycms-settings-*` branch this deployment doesn't own),
- * and api/branch.ts's `createBranchHandler` (reject a user-requested branch
- * whose SANITIZED name falls in this namespace).
+ * Prefix reserved for CanopyCMS settings branches (`canopycms-settings-{name}`;
+ * built by operating-mode/client-unsafe-strategy.ts's `getSettingsBranchName`).
+ * Exported from this dependency-free module -- not rebuilt ad hoc at each call
+ * site -- so every consumer of the namespace agrees on the exact string:
+ * worker/git-sync.ts's `pushSettingsBranches` never pushes a
+ * `canopycms-settings-*` branch this deployment doesn't own, and api/branch.ts's
+ * `createBranchHandler` rejects a user-requested branch whose SANITIZED name
+ * falls in this namespace.
  *
- * Two CanopyCMS deployments can share one GitHub repo, each with its own
- * settings branch under this prefix (`canopycms-settings-prod` vs
- * `canopycms-settings-staging`, say). A content-branch request that lands on
- * ANOTHER deployment's settings branch name would silently corrupt that
- * deployment's permissions/groups the next time its worker treats the ref as
- * an orphan settings branch -- so the whole prefix is reserved for branch
- * creation, not just this deployment's own settings branch name.
+ * The WHOLE prefix is reserved, not just this deployment's own settings branch:
+ * two deployments can share one GitHub repo, and a content branch landing on
+ * the other's settings-branch name silently corrupts that deployment's
+ * permissions/groups once its worker treats the ref as an orphan settings
+ * branch.
  */
 export declare const RESERVED_SETTINGS_BRANCH_PREFIX = "canopycms-settings-";
 /**
@@ -42,16 +34,14 @@ export declare const RESERVED_SETTINGS_BRANCH_PREFIX = "canopycms-settings-";
  *
  * http/router.ts's `compareSpecificity` ranks a literal pattern segment above a
  * `:param`, so a branch named e.g. `admin` has its `/:branch/...` routes
- * shadowed by the static `/admin/...` ones. The failure is a *partial* one,
- * which is what makes it confusing: bare `GET /admin` still reaches the branch
- * handler (there is no single-segment static `/admin` route), so the branch
- * looks half-alive while every nested route 404s or 403s.
+ * shadowed by the static `/admin/...` ones -- and only partially, which is what
+ * makes it confusing: bare `GET /admin` still reaches the branch handler, so the
+ * branch looks half-alive while every nested route 404s or 403s.
  *
- * Lives in this dependency-free module for the same reason as
- * {@link RESERVED_SETTINGS_BRANCH_PREFIX}: api/validators.ts is imported *by*
- * the route modules, so nothing on the validation side can import the router to
- * derive this at runtime without a cycle. http/router.test.ts derives the same
- * set from the live route table and asserts it equals this constant, so adding
- * a new top-level namespace fails that test until this list is updated.
+ * Listed rather than derived at runtime because api/validators.ts is imported
+ * *by* the route modules, so importing the router here would cycle.
+ * http/router.test.ts derives the same set from the live route table and asserts
+ * it equals this constant, so a new top-level namespace fails that test until
+ * this list is updated.
  */
 export declare const RESERVED_ROUTE_BRANCH_NAMES: readonly string[];

package/dist/paths/branch-name.js

@@ -1,20 +1,15 @@
 /**
- * Branch-name sanitization, isolated in a dependency-free module.
+ * Branch-name sanitization, isolated in a dependency-free module (imports
+ * nothing but types; same pattern as assets/asset-prefixes.ts).
  *
- * Deliberately imports nothing but types: `paths/branch.ts` (the path
- * RESOLUTION module) pulls `node:fs` and the operating-mode strategies, so
- * isomorphic/client-reachable code (e.g. authorization/protected-branch.ts,
- * which the editor bundle reaches via api/guards.ts) must get
- * `sanitizeBranchName` from HERE, never from `paths/branch.ts` — a `node:`
- * import in that graph breaks adopters' production `next build` of the
- * editor bundle. Same pattern as assets/asset-prefixes.ts.
- */
-/**
- * Sanitize a branch name for use in filesystem paths.
- * - Replaces invalid characters with hyphens
- * - Collapses multiple hyphens
- * - Trims leading/trailing dots
+ * Client-reachable code (e.g. authorization/protected-branch.ts, which the
+ * editor bundle reaches via api/guards.ts) MUST import `sanitizeBranchName`
+ * from HERE, never from `paths/branch.ts` or the `paths` barrel: both pull
+ * `node:fs` and the operating-mode strategies, and a `node:` import in that
+ * graph breaks adopters' production `next build` of the editor bundle.
+ * `pnpm lint:bundle` enforces it.
  */
+/** Sanitize a branch name for use in filesystem paths. */
 export function sanitizeBranchName(branchName) {
     const replaced = branchName.replace(/[^a-zA-Z0-9._-]/g, '-');
     const squashed = replaced.replace(/-+/g, '-');
@@ -22,23 +17,20 @@ export function sanitizeBranchName(branchName) {
     return (trimmedDots || 'branch');
 }
 /**
- * Prefix reserved for CanopyCMS settings branches (`canopycms-settings-{name}`,
- * see operating-mode/client-unsafe-strategy.ts's `getSettingsBranchName` and
- * operating-mode/deployment-name.ts's `resolveDeploymentName`). Exported from
- * this dependency-free module -- not constructed ad hoc at each call site --
- * so every consumer that needs to recognize the settings-branch namespace
- * agrees on the exact string: worker/git-sync.ts's `pushSettingsBranches`
- * (never push a `canopycms-settings-*` branch this deployment doesn't own),
- * and api/branch.ts's `createBranchHandler` (reject a user-requested branch
- * whose SANITIZED name falls in this namespace).
+ * Prefix reserved for CanopyCMS settings branches (`canopycms-settings-{name}`;
+ * built by operating-mode/client-unsafe-strategy.ts's `getSettingsBranchName`).
+ * Exported from this dependency-free module -- not rebuilt ad hoc at each call
+ * site -- so every consumer of the namespace agrees on the exact string:
+ * worker/git-sync.ts's `pushSettingsBranches` never pushes a
+ * `canopycms-settings-*` branch this deployment doesn't own, and api/branch.ts's
+ * `createBranchHandler` rejects a user-requested branch whose SANITIZED name
+ * falls in this namespace.
  *
- * Two CanopyCMS deployments can share one GitHub repo, each with its own
- * settings branch under this prefix (`canopycms-settings-prod` vs
- * `canopycms-settings-staging`, say). A content-branch request that lands on
- * ANOTHER deployment's settings branch name would silently corrupt that
- * deployment's permissions/groups the next time its worker treats the ref as
- * an orphan settings branch -- so the whole prefix is reserved for branch
- * creation, not just this deployment's own settings branch name.
+ * The WHOLE prefix is reserved, not just this deployment's own settings branch:
+ * two deployments can share one GitHub repo, and a content branch landing on
+ * the other's settings-branch name silently corrupts that deployment's
+ * permissions/groups once its worker treats the ref as an orphan settings
+ * branch.
  */
 export const RESERVED_SETTINGS_BRANCH_PREFIX = 'canopycms-settings-';
 /**
@@ -46,17 +38,15 @@ export const RESERVED_SETTINGS_BRANCH_PREFIX = 'canopycms-settings-';
  *
  * http/router.ts's `compareSpecificity` ranks a literal pattern segment above a
  * `:param`, so a branch named e.g. `admin` has its `/:branch/...` routes
- * shadowed by the static `/admin/...` ones. The failure is a *partial* one,
- * which is what makes it confusing: bare `GET /admin` still reaches the branch
- * handler (there is no single-segment static `/admin` route), so the branch
- * looks half-alive while every nested route 404s or 403s.
+ * shadowed by the static `/admin/...` ones -- and only partially, which is what
+ * makes it confusing: bare `GET /admin` still reaches the branch handler, so the
+ * branch looks half-alive while every nested route 404s or 403s.
  *
- * Lives in this dependency-free module for the same reason as
- * {@link RESERVED_SETTINGS_BRANCH_PREFIX}: api/validators.ts is imported *by*
- * the route modules, so nothing on the validation side can import the router to
- * derive this at runtime without a cycle. http/router.test.ts derives the same
- * set from the live route table and asserts it equals this constant, so adding
- * a new top-level namespace fails that test until this list is updated.
+ * Listed rather than derived at runtime because api/validators.ts is imported
+ * *by* the route modules, so importing the router here would cycle.
+ * http/router.test.ts derives the same set from the live route table and asserts
+ * it equals this constant, so a new top-level namespace fails that test until
+ * this list is updated.
  */
 export const RESERVED_ROUTE_BRANCH_NAMES = [
     'admin',

package/dist/paths/branch.d.ts

@@ -1,8 +1,4 @@
-/**
- * Branch path resolution utilities.
- *
- * Handles resolving branch names to workspace directories.
- */
+/** Branch path resolution utilities. */
 import type { BranchContext } from '../types.js';
 import { OperatingMode } from '../operating-mode/index.js';
 export interface BranchPathOptions {
@@ -15,24 +11,14 @@ export interface BranchPathResult {
     baseRoot: string;
     branchName: string;
 }
+/** @internal Exported for tests. */
 export declare class BranchPathError extends Error {
 }
 import { sanitizeBranchName } from './branch-name.js';
+/** @internal Exported for tests. */
 export { sanitizeBranchName };
-/**
- * Resolve branch name to workspace paths.
- * Validates for path traversal attacks.
- */
+/** Resolve a branch name to workspace paths, rejecting path traversal. */
 export declare function resolveBranchPath(options: BranchPathOptions): BranchPathResult;
-/**
- * Ensure the branch workspace directory exists.
- */
 export declare function ensureBranchRoot(options: BranchPathOptions): Promise<BranchPathResult>;
-/**
- * Get the default base directory for branch workspaces.
- */
 export declare function getDefaultBranchBase(mode: OperatingMode, override?: string): string;
-/**
- * Resolve branch paths from a branch context.
- */
 export declare function resolveBranchPaths(branchContext: BranchContext, mode: OperatingMode, basePathOverride?: string): BranchPathResult;

package/dist/paths/branch.js

@@ -1,26 +1,19 @@
-/**
- * Branch path resolution utilities.
- *
- * Handles resolving branch names to workspace directories.
- */
+/** Branch path resolution utilities. */
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { operatingStrategy } from '../operating-mode/index.js';
+/** @internal Exported for tests. */
 export class BranchPathError extends Error {
 }
-// Moved to ./branch-name (dependency-free) so client-reachable modules can
-// use it without dragging this file's node:fs / operating-mode imports into
-// browser bundles. Imported for local use + re-exported for existing
-// server-side importers.
+// 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';
+/** @internal Exported for tests. */
 export { sanitizeBranchName };
 const resolveContentBranchesRoot = (mode, override) => {
     return operatingStrategy(mode).getContentBranchesRoot(override);
 };
-/**
- * Resolve branch name to workspace paths.
- * Validates for path traversal attacks.
- */
+/** Resolve a branch name to workspace paths, rejecting path traversal. */
 export function resolveBranchPath(options) {
     if (options.branchName.includes('..')) {
         throw new BranchPathError('Branch name cannot contain traversal segments');
@@ -42,23 +35,14 @@ export function resolveBranchPath(options) {
     }
     return { branchRoot, baseRoot: normalizedBase, branchName: safeBranch };
 }
-/**
- * Ensure the branch workspace directory exists.
- */
 export async function ensureBranchRoot(options) {
     const result = resolveBranchPath(options);
     await fs.mkdir(result.branchRoot, { recursive: true });
     return result;
 }
-/**
- * Get the default base directory for branch workspaces.
- */
 export function getDefaultBranchBase(mode, override) {
     return resolveContentBranchesRoot(mode, override);
 }
-/**
- * Resolve branch paths from a branch context.
- */
 export function resolveBranchPaths(branchContext, mode, basePathOverride) {
     if (branchContext.branchRoot || branchContext.baseRoot) {
         const baseRoot = path.resolve(branchContext.baseRoot ?? resolveContentBranchesRoot(mode, basePathOverride));

package/dist/paths/index.d.ts

@@ -1,17 +1,6 @@
 /**
- * Path utilities for CanopyCMS
- *
- * This module consolidates path handling utilities that were previously
- * scattered across multiple files:
- * - normalize.ts: Path normalization and creation
- * - validation.ts: Security validation for paths
- * - branch.ts: Branch workspace path resolution
- * - types.ts: Branded types for type safety
- *
- * Usage:
- * ```ts
- * import { normalizeFilesystemPath, createLogicalPath, parseSlug } from '../paths/index.js'
- * ```
+ * Path utilities. Client-reachable code deep-imports `./branch-name` instead,
+ * 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';

package/dist/paths/index.js

@@ -1,32 +1,12 @@
 /**
- * Path utilities for CanopyCMS
- *
- * This module consolidates path handling utilities that were previously
- * scattered across multiple files:
- * - normalize.ts: Path normalization and creation
- * - validation.ts: Security validation for paths
- * - branch.ts: Branch workspace path resolution
- * - types.ts: Branded types for type safety
- *
- * Usage:
- * ```ts
- * import { normalizeFilesystemPath, createLogicalPath, parseSlug } from '../paths/index.js'
- * ```
+ * Path utilities. Client-reachable code deep-imports `./branch-name` instead,
+ * 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';
 // Normalization utilities (server-only, requires Node.js path module)
 export { validateAndNormalizePath } from './normalize-server.js';
-// Validation utilities
-export { validateContentPath, isValidCollectionPath, sanitizeForPath, 
-// Path type detection and parsing
-hasEmbeddedContentId, looksLikePhysicalPath, looksLikeLogicalPath, parseLogicalPath, parsePhysicalPath, isValidContentId, 
-// Branded type validation and parsing
-parseContentId, parseBranchName, parseSlug, } from './validation.js';
-// Path resolution utilities
+export { validateContentPath, isValidCollectionPath, sanitizeForPath, hasEmbeddedContentId, looksLikePhysicalPath, looksLikeLogicalPath, parseLogicalPath, parsePhysicalPath, isValidContentId, parseContentId, parseBranchName, parseSlug, } from './validation.js';
 export { resolveLogicalPath } from './resolve.js';
-// Branch path utilities
 export { resolveBranchPath, ensureBranchRoot, getDefaultBranchBase, resolveBranchPaths, BranchPathError, } from './branch.js';
-// From the dependency-free module (NOT ./branch, which imports node:fs) so
-// client-reachable importers of 'canopycms/src/paths' stay browser-safe.
 export { sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX, RESERVED_ROUTE_BRANCH_NAMES, } from './branch-name.js';

package/dist/paths/normalize-server.d.ts

@@ -1,19 +1,7 @@
 /**
- * Server-only path normalization utilities.
- *
- * These functions depend on Node.js 'path' module and cannot be used in client code.
- * Client-safe functions are in normalize.ts.
+ * Server-only path normalization utilities: these depend on `node:path` and
+ * must not reach a client bundle. Client-safe equivalents are in normalize.ts.
  */
 import type { PathValidationResult } from './types.js';
-/**
- * Validate and normalize a path relative to a root directory.
- * Checks for path traversal attacks.
- *
- * NOTE: This function uses Node.js path module and is server-only.
- * For client code, use the pure functions in normalize.ts.
- *
- * @param root - The root directory
- * @param target - The target path to validate
- * @returns Validation result with normalized relative path if valid
- */
+/** Normalize `target` relative to `root`, rejecting anything that escapes it. */
 export declare function validateAndNormalizePath(root: string, target: string): PathValidationResult;

package/dist/paths/normalize-server.js

@@ -1,21 +1,9 @@
 /**
- * Server-only path normalization utilities.
- *
- * These functions depend on Node.js 'path' module and cannot be used in client code.
- * Client-safe functions are in normalize.ts.
+ * Server-only path normalization utilities: these depend on `node:path` and
+ * must not reach a client bundle. Client-safe equivalents are in normalize.ts.
  */
 import { sep, resolve, relative } from 'node:path';
-/**
- * Validate and normalize a path relative to a root directory.
- * Checks for path traversal attacks.
- *
- * NOTE: This function uses Node.js path module and is server-only.
- * For client code, use the pure functions in normalize.ts.
- *
- * @param root - The root directory
- * @param target - The target path to validate
- * @returns Validation result with normalized relative path if valid
- */
+/** Normalize `target` relative to `root`, rejecting anything that escapes it. */
 export function validateAndNormalizePath(root, target) {
     const resolvedRoot = resolve(root);
     const withSep = resolvedRoot.endsWith(sep) ? resolvedRoot : `${resolvedRoot}${sep}`;

package/dist/paths/normalize.d.ts

@@ -1,66 +1,46 @@
 /**
- * Path normalization utilities (client-safe).
- *
- * Consolidates the various path normalization patterns used across the codebase
- * into a single, well-tested module.
- *
- * NOTE: These functions are pure and can be used in both client and server code.
- * Server-only functions that depend on Node.js 'path' module are in normalize-server.ts.
+ * Path normalization utilities. Pure, so client-safe; the ones that need
+ * `node:path` live in normalize-server.ts.
  */
 import type { LogicalPath, PhysicalPath } from './types.js';
 /**
- * Normalize a filesystem path by:
- * - Converting backslashes to forward slashes
- * - Removing empty segments
- * - Removing leading/trailing slashes
- *
- * This is the foundational normalization used by most path operations.
+ * Split on either separator, dropping empty segments, and rejoin with `/`:
+ * backslashes become forward slashes and leading/trailing/repeated slashes go.
+ * Most other path operations here build on it.
  *
  * @example
  * normalizeFilesystemPath('content\\posts\\\\my-post') // 'content/posts/my-post'
- * normalizeFilesystemPath('/content/posts/') // 'content/posts'
  */
 export declare function normalizeFilesystemPath(path: string): string;
 /**
- * Normalize a collection path by removing any content root prefix
- * and normalizing separators.
+ * Normalize separators and strip any leading content-root prefix.
  *
  * @example
- * normalizeCollectionPath('content/posts') // 'posts'
  * normalizeCollectionPath('content\\blog\\posts') // 'blog/posts'
- * normalizeCollectionPath('posts') // 'posts'
  */
 export declare function normalizeCollectionPath(collectionPath: string, contentRoot?: string): string;
 /**
  * Check if a path contains traversal sequences (.., etc.)
  */
 export declare function hasTraversalSequence(path: string): boolean;
-/**
- * Create a logical path from segments.
- * Validates that no segment contains path traversal.
- *
- * @example
- * createLogicalPath('content', 'posts', 'my-post') // 'content/posts/my-post' as LogicalPath
- */
+/** Join segments into a LogicalPath, throwing on a traversal sequence. */
 export declare function createLogicalPath(...segments: string[]): LogicalPath;
 /**
- * Create a physical path from segments.
- * This is for paths that may contain embedded IDs.
- *
- * @example
- * createPhysicalPath('content', 'posts', 'my-post.ABC123.mdx') // as PhysicalPath
+ * Join segments into a PhysicalPath (segments may carry embedded content IDs,
+ * e.g. `my-post.ABC123.mdx`), throwing on a traversal sequence.
+ * @internal Exported for tests.
  */
 export declare function createPhysicalPath(...segments: string[]): PhysicalPath;
 /**
  * Strip leading and trailing slashes from a path or URL segment.
  *
  * @example
- * trimSlashes('/docs/guides/') // 'docs/guides'
  * trimSlashes('///multi///') // 'multi'
  */
 export declare function trimSlashes(path: string): string;
 /**
- * Join path segments with forward slashes.
- * Does not validate - use createLogicalPath/createPhysicalPath for validation.
+ * Join path segments with forward slashes. Does NOT check for traversal --
+ * use createLogicalPath/createPhysicalPath where the result is used as a path.
+ * @internal Exported for tests.
  */
 export declare function joinPath(...segments: string[]): string;

package/dist/paths/normalize.js

@@ -1,23 +1,14 @@
 /**
- * Path normalization utilities (client-safe).
- *
- * Consolidates the various path normalization patterns used across the codebase
- * into a single, well-tested module.
- *
- * NOTE: These functions are pure and can be used in both client and server code.
- * Server-only functions that depend on Node.js 'path' module are in normalize-server.ts.
+ * Path normalization utilities. Pure, so client-safe; the ones that need
+ * `node:path` live in normalize-server.ts.
  */
 /**
- * Normalize a filesystem path by:
- * - Converting backslashes to forward slashes
- * - Removing empty segments
- * - Removing leading/trailing slashes
- *
- * This is the foundational normalization used by most path operations.
+ * Split on either separator, dropping empty segments, and rejoin with `/`:
+ * backslashes become forward slashes and leading/trailing/repeated slashes go.
+ * Most other path operations here build on it.
  *
  * @example
  * normalizeFilesystemPath('content\\posts\\\\my-post') // 'content/posts/my-post'
- * normalizeFilesystemPath('/content/posts/') // 'content/posts'
  */
 export function normalizeFilesystemPath(path) {
     return path
@@ -26,13 +17,10 @@ export function normalizeFilesystemPath(path) {
         .join('/');
 }
 /**
- * Normalize a collection path by removing any content root prefix
- * and normalizing separators.
+ * Normalize separators and strip any leading content-root prefix.
  *
  * @example
- * normalizeCollectionPath('content/posts') // 'posts'
  * normalizeCollectionPath('content\\blog\\posts') // 'blog/posts'
- * normalizeCollectionPath('posts') // 'posts'
  */
 export function normalizeCollectionPath(collectionPath, contentRoot = 'content') {
     const normalized = normalizeFilesystemPath(collectionPath);
@@ -49,13 +37,7 @@ export function hasTraversalSequence(path) {
     const normalized = normalizeFilesystemPath(path);
     return normalized.includes('..');
 }
-/**
- * Create a logical path from segments.
- * Validates that no segment contains path traversal.
- *
- * @example
- * createLogicalPath('content', 'posts', 'my-post') // 'content/posts/my-post' as LogicalPath
- */
+/** Join segments into a LogicalPath, throwing on a traversal sequence. */
 export function createLogicalPath(...segments) {
     const normalized = segments
         .map((s) => normalizeFilesystemPath(s))
@@ -67,11 +49,9 @@ export function createLogicalPath(...segments) {
     return normalized;
 }
 /**
- * Create a physical path from segments.
- * This is for paths that may contain embedded IDs.
- *
- * @example
- * createPhysicalPath('content', 'posts', 'my-post.ABC123.mdx') // as PhysicalPath
+ * Join segments into a PhysicalPath (segments may carry embedded content IDs,
+ * e.g. `my-post.ABC123.mdx`), throwing on a traversal sequence.
+ * @internal Exported for tests.
  */
 export function createPhysicalPath(...segments) {
     const normalized = segments
@@ -87,7 +67,6 @@ export function createPhysicalPath(...segments) {
  * Strip leading and trailing slashes from a path or URL segment.
  *
  * @example
- * trimSlashes('/docs/guides/') // 'docs/guides'
  * trimSlashes('///multi///') // 'multi'
  */
 export function trimSlashes(path) {
@@ -101,8 +80,9 @@ export function trimSlashes(path) {
     return path.slice(start, end);
 }
 /**
- * Join path segments with forward slashes.
- * Does not validate - use createLogicalPath/createPhysicalPath for validation.
+ * Join path segments with forward slashes. Does NOT check for traversal --
+ * use createLogicalPath/createPhysicalPath where the result is used as a path.
+ * @internal Exported for tests.
  */
 export function joinPath(...segments) {
     return segments

package/dist/paths/resolve.d.ts

@@ -4,26 +4,13 @@
 import type { FlatSchemaItem } from '../config/index.js';
 import type { LogicalPath } from './types.js';
 /**
- * Resolve a physical collection path to its logical path.
- *
- * Physical paths contain embedded IDs (e.g., "content/authors.q52DCVPuH4ga"),
- * while logical paths are schema-defined (e.g., "content/authors").
- *
- * This function matches physical path segments to logical path segments,
- * accounting for ID suffixes in physical paths.
- *
- * @param physicalPath - The physical filesystem path with embedded IDs
- * @param schemaItems - Iterable of schema items to search
- * @returns The matching logical path, or the physical path if no match found
- *
- * @example
- * // Match physical to logical
- * resolveLogicalPath("content/authors.q52DCVPuH4ga", schemaItems)
- * // Returns: "content/authors"
+ * Resolve a physical collection path (segments carry embedded IDs, e.g.
+ * "content/authors.q52DCVPuH4ga") to its schema-defined logical path
+ * ("content/authors"), or back to the physical path when nothing matches.
  *
  * @example
- * // Nested collections
  * resolveLogicalPath("content/docs.ABC/api.DEF", schemaItems)
  * // Returns: "content/docs/api"
+ * @internal Exported for tests.
  */
 export declare function resolveLogicalPath(physicalPath: string, schemaItems: Iterable<FlatSchemaItem>): LogicalPath | string;