canopycms 0.0.67-int.90 → 0.0.67

package/dist/paths/resolve.js

@@ -2,40 +2,23 @@
  * Path resolution utilities for converting between physical and logical paths.
  */
 /**
- * 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 function resolveLogicalPath(physicalPath, schemaItems) {
     const pathSegments = physicalPath.split('/');
     for (const schemaItem of schemaItems) {
         if (schemaItem.type === 'collection') {
             const logicalSegments = schemaItem.logicalPath.split('/');
-            // Check if all logical segments match the corresponding physical segments
-            // (ignoring the ID part after the dot in directory names)
             if (pathSegments.length === logicalSegments.length) {
                 const matches = logicalSegments.every((logicalSeg, i) => {
                     const physicalSeg = pathSegments[i];
-                    // Physical segment might have ID: "authors.q52DCVPuH4ga"
-                    // Logical segment: "authors"
                     // Match if identical OR if physical starts with logical + '.'
                     return physicalSeg === logicalSeg || physicalSeg.startsWith(logicalSeg + '.');
                 });
@@ -45,6 +28,5 @@ export function resolveLogicalPath(physicalPath, schemaItems) {
             }
         }
     }
-    // Fallback: return the physical path if we can't find a match
     return physicalPath;
 }

package/dist/paths/types.d.ts

@@ -1,62 +1,40 @@
 /**
- * Path type definitions for CanopyCMS
- *
- * These branded types provide compile-time safety to prevent accidentally
- * mixing logical paths (content/posts/my-post) with physical filesystem
- * paths (content/posts/my-post.ABC123.mdx).
- */
-/**
- * A logical content path without embedded IDs.
- * Used in APIs, URLs, and user-facing contexts.
- * Example: "content/posts/my-post"
+ * Branded path types. The brands exist to stop logical paths
+ * (content/posts/my-post) being passed where physical filesystem paths
+ * (content/posts/my-post.ABC123.mdx) are expected, and vice versa.
  */
+/** A content path with no embedded IDs, as APIs and URLs carry it. */
 export type LogicalPath = string & {
     readonly __brand: 'LogicalPath';
 };
-/**
- * A physical filesystem path that may contain embedded IDs.
- * Used for actual file operations.
- * Example: "content/posts/my-post.ABC123.mdx"
- */
+/** A filesystem path, which may carry embedded IDs, as file operations need. */
 export type PhysicalPath = string & {
     readonly __brand: 'PhysicalPath';
 };
-/**
- * A branch name that has been sanitized for filesystem use.
- */
+/** A branch name already sanitized for filesystem use. */
 export type SanitizedBranchName = string & {
     readonly __brand: 'SanitizedBranchName';
 };
-/**
- * A git branch name (before sanitization for filesystem use).
- * Example: "feature/add-dark-mode" or "main"
- */
+/** A git branch name, not yet sanitized: "feature/add-dark-mode", "main". */
 export type BranchName = string & {
     readonly __brand: 'BranchName';
 };
 /**
- * A 12-character Base58-encoded content ID.
- * Used to uniquely identify entries and collections in filenames.
- * Example: "bChqT78gcaLd"
+ * A 12-character Base58 content ID ("bChqT78gcaLd"), which uniquely identifies
+ * an entry or collection within a filename.
  */
 export type ContentId = string & {
     readonly __brand: 'ContentId';
 };
 /**
- * Sentinel ContentId for the root content directory (which has no embedded ID in its name).
- * Uses underscores — can never collide with real 12-char Base58 IDs (which exclude `_`).
+ * Sentinel ContentId for the root content directory, whose name carries no
+ * embedded ID. Underscores cannot collide with Base58 IDs, which exclude `_`.
  */
 export declare const ROOT_COLLECTION_ID: ContentId;
-/**
- * A validated, lowercase slug used for collections and entries.
- * Example: "posts", "my-first-post", "getting-started"
- */
+/** A validated, lowercase collection or entry slug: "my-first-post". */
 export type Slug = string & {
     readonly __brand: 'Slug';
 };
-/**
- * Path validation result.
- */
 export interface PathValidationResult {
     valid: boolean;
     error?: string;

package/dist/paths/types.js

@@ -1,12 +1,10 @@
 /**
- * Path type definitions for CanopyCMS
- *
- * These branded types provide compile-time safety to prevent accidentally
- * mixing logical paths (content/posts/my-post) with physical filesystem
- * paths (content/posts/my-post.ABC123.mdx).
+ * Branded path types. The brands exist to stop logical paths
+ * (content/posts/my-post) being passed where physical filesystem paths
+ * (content/posts/my-post.ABC123.mdx) are expected, and vice versa.
  */
 /**
- * Sentinel ContentId for the root content directory (which has no embedded ID in its name).
- * Uses underscores — can never collide with real 12-char Base58 IDs (which exclude `_`).
+ * Sentinel ContentId for the root content directory, whose name carries no
+ * embedded ID. Underscores cannot collide with Base58 IDs, which exclude `_`.
  */
 export const ROOT_COLLECTION_ID = '__rootcoll__';

package/dist/paths/validation.d.ts

@@ -1,82 +1,40 @@
-/**
- * Path validation utilities.
- *
- * Security-focused validation for content paths and slugs.
- */
+/** Security-focused validation for content paths, IDs, branch names and slugs. */
 import type { LogicalPath, PhysicalPath, ContentId, BranchName, Slug } from './types.js';
 /**
- * Validate a content path for security.
- *
- * @param path - The path to validate
- * @param rootPath - The root directory (for traversal check)
- * @returns Validation result
+ * Reject a content path that traverses, or that escapes `rootPath`.
+ * @internal Exported for tests.
  */
 export declare function validateContentPath(path: string, rootPath: string): {
     valid: boolean;
     error?: string;
 };
 /**
- * Validate a collection path.
- *
- * @param collectionPath - The collection path to validate
- * @returns true if valid, false otherwise
+ * A collection path must be non-empty, traversal-free, and `[A-Za-z0-9_/-]+`.
+ * @internal Exported for tests.
  */
 export declare function isValidCollectionPath(collectionPath: string): boolean;
 /**
- * Sanitize a string for use in paths by removing dangerous characters.
- *
- * @param input - The string to sanitize
- * @returns Sanitized string safe for path use
+ * Strip the characters that make a string unsafe as a path component.
+ * @internal Exported for tests.
  */
 export declare function sanitizeForPath(input: string): string;
 /**
- * Check if a path segment contains an embedded content ID.
- *
- * Physical paths have segments with embedded 12-char IDs:
- * - `post.my-slug.abc123def456.json` (entry file)
- * - `posts.abc123def456` (collection directory)
- *
- * @param segment - A single path segment (no slashes)
- * @returns true if segment contains embedded ID pattern
+ * Whether a single path segment (no slashes) carries an embedded content ID.
+ * @internal Exported for tests.
  */
 export declare function hasEmbeddedContentId(segment: string): boolean;
 /**
- * Check if a path appears to be a physical path (contains embedded content IDs).
- *
- * Physical paths have the format:
- * - `content/posts.abc123/post.hello.def456.json`
- *
- * Logical paths do not have embedded IDs:
- * - `content/posts/hello` or `posts/hello`
- *
- * @param path - The path to check
- * @returns true if any segment contains an embedded content ID
+ * Whether any segment carries an embedded content ID:
+ * `content/posts.abc123/post.hello.def456.json` does, `content/posts/hello`
+ * does not.
+ * @internal Exported for tests.
  */
 export declare function looksLikePhysicalPath(path: string): boolean;
-/**
- * Check if a path appears to be a logical path (no embedded content IDs).
- *
- * @param path - The path to check
- * @returns true if no segments contain embedded content IDs
- */
+/** @internal Exported for tests. */
 export declare function looksLikeLogicalPath(path: string): boolean;
 /**
- * Validate and cast a string to LogicalPath.
- *
- * Use this at API boundaries to validate incoming path strings
- * and cast them to the branded LogicalPath type.
- *
- * @param path - The path string to validate
- * @returns Object with success flag and either the typed path or an error
- *
- * @example
- * ```ts
- * const result = parseLogicalPath(params.collectionPath)
- * if (!result.ok) {
- *   return { ok: false, status: 400, error: result.error }
- * }
- * const collectionPath: LogicalPath = result.path
- * ```
+ * Validate an incoming path string at an API boundary and cast it to the
+ * branded LogicalPath type.
  */
 export declare function parseLogicalPath(path: string): {
     ok: true;
@@ -86,13 +44,9 @@ export declare function parseLogicalPath(path: string): {
     error: string;
 };
 /**
- * Validate and cast a string to PhysicalPath.
- *
- * Use this at API boundaries to validate incoming path strings
- * and cast them to the branded PhysicalPath type.
- *
- * @param path - The path string to validate
- * @returns Object with success flag and either the typed path or an error
+ * Validate an incoming path string at an API boundary and cast it to the
+ * branded PhysicalPath type.
+ * @internal Exported for tests.
  */
 export declare function parsePhysicalPath(path: string): {
     ok: true;
@@ -101,29 +55,8 @@ export declare function parsePhysicalPath(path: string): {
     ok: false;
     error: string;
 };
-/**
- * Check if a string is a valid 12-character content ID.
- *
- * @param id - The string to check
- * @returns true if valid Base58 12-char ID
- */
 export declare function isValidContentId(id: string): boolean;
-/**
- * Parse and validate a ContentId from a string.
- * Validates Base58 format and 12-character length.
- *
- * @param id - The string to validate
- * @returns Object with success flag and either the typed ID or an error
- *
- * @example
- * ```ts
- * const result = parseContentId(fileId)
- * if (!result.ok) {
- *   throw new Error(result.error)
- * }
- * const contentId: ContentId = result.id
- * ```
- */
+/** Validate a string as a 12-character Base58 ContentId and cast it. */
 export declare function parseContentId(id: string): {
     ok: true;
     id: ContentId;
@@ -131,22 +64,7 @@ export declare function parseContentId(id: string): {
     ok: false;
     error: string;
 };
-/**
- * Parse and validate a BranchName.
- * Checks git branch naming rules.
- *
- * @param name - The branch name to validate
- * @returns Object with success flag and either the typed name or an error
- *
- * @example
- * ```ts
- * const result = parseBranchName(params.branch)
- * if (!result.ok) {
- *   return { ok: false, status: 400, error: result.error }
- * }
- * const branchName: BranchName = result.name
- * ```
- */
+/** Validate a branch name against git's ref rules and cast it to BranchName. */
 export declare function parseBranchName(name: string): {
     ok: true;
     name: BranchName;
@@ -154,22 +72,7 @@ export declare function parseBranchName(name: string): {
     ok: false;
     error: string;
 };
-/**
- * Parse and validate a slug (collection or entry).
- * Validates format and length constraints.
- *
- * @param slug - The slug to validate
- * @returns Object with success flag and either the typed slug or an error
- *
- * @example
- * ```ts
- * const result = parseSlug(params.slug)
- * if (!result.ok) {
- *   return { ok: false, status: 400, error: result.error }
- * }
- * const slug: Slug = result.slug
- * ```
- */
+/** Validate a collection or entry slug and cast it to Slug. */
 export declare function parseSlug(slug: string): {
     ok: true;
     slug: Slug;

package/dist/paths/validation.js

@@ -1,41 +1,25 @@
-/**
- * Path validation utilities.
- *
- * Security-focused validation for content paths and slugs.
- */
+/** Security-focused validation for content paths, IDs, branch names and slugs. */
 import { normalizeFilesystemPath, hasTraversalSequence } from './normalize.js';
-/**
- * Base58 alphabet used for content IDs (excludes ambiguous: 0, O, I, l)
- */
+/** Base58 alphabet for content IDs: excludes the ambiguous 0, O, I and l. */
 const BASE58_PATTERN = '[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]';
-/**
- * Pattern matching exactly a 12-character content ID
- */
 const CONTENT_ID_PATTERN = new RegExp(`^${BASE58_PATTERN}{12}$`);
 /**
- * Pattern matching a physical path segment with embedded ID.
- * Matches patterns like:
- * - `post.my-slug.abc123def456.json` (entry)
- * - `posts.abc123def456` (collection directory)
+ * A physical path segment carries an embedded ID: `posts.abc123def456` for a
+ * collection directory, `post.my-slug.abc123def456.json` for an entry file.
  */
 const PHYSICAL_SEGMENT_PATTERN = new RegExp(`\\.${BASE58_PATTERN}{12}(?:\\.[a-z]+)?$`);
 /**
- * Validate a content path for security.
- *
- * @param path - The path to validate
- * @param rootPath - The root directory (for traversal check)
- * @returns Validation result
+ * Reject a content path that traverses, or that escapes `rootPath`.
+ * @internal Exported for tests.
  */
 export function validateContentPath(path, rootPath) {
     const normalized = normalizeFilesystemPath(path);
-    // Check for traversal sequences
     if (hasTraversalSequence(normalized)) {
         return { valid: false, error: 'Path contains traversal sequence' };
     }
-    // Check path doesn't escape root
     const normalizedRoot = normalizeFilesystemPath(rootPath);
     if (!normalized.startsWith(normalizedRoot) && normalized !== normalizedRoot) {
-        // Allow paths that are relative within the root
+        // Not already rooted: re-check as a path relative to the root.
         const normalizedPath = `${normalizedRoot}/${normalized}`;
         if (hasTraversalSequence(normalizedPath)) {
             return { valid: false, error: 'Path escapes root directory' };
@@ -44,29 +28,23 @@ export function validateContentPath(path, rootPath) {
     return { valid: true };
 }
 /**
- * Validate a collection path.
- *
- * @param collectionPath - The collection path to validate
- * @returns true if valid, false otherwise
+ * A collection path must be non-empty, traversal-free, and `[A-Za-z0-9_/-]+`.
+ * @internal Exported for tests.
  */
 export function isValidCollectionPath(collectionPath) {
     if (!collectionPath || collectionPath.length === 0) {
         return false;
     }
-    // Normalize and check for traversal
     const normalized = normalizeFilesystemPath(collectionPath);
     if (hasTraversalSequence(normalized)) {
         return false;
     }
-    // Collection paths should only contain alphanumeric, hyphens, underscores, and forward slashes
     const validPattern = /^[a-zA-Z0-9_/-]+$/;
     return validPattern.test(normalized);
 }
 /**
- * Sanitize a string for use in paths by removing dangerous characters.
- *
- * @param input - The string to sanitize
- * @returns Sanitized string safe for path use
+ * Strip the characters that make a string unsafe as a path component.
+ * @internal Exported for tests.
  */
 export function sanitizeForPath(input) {
     return input
@@ -76,73 +54,39 @@ export function sanitizeForPath(input) {
         .trim();
 }
 /**
- * Check if a path segment contains an embedded content ID.
- *
- * Physical paths have segments with embedded 12-char IDs:
- * - `post.my-slug.abc123def456.json` (entry file)
- * - `posts.abc123def456` (collection directory)
- *
- * @param segment - A single path segment (no slashes)
- * @returns true if segment contains embedded ID pattern
+ * Whether a single path segment (no slashes) carries an embedded content ID.
+ * @internal Exported for tests.
  */
 export function hasEmbeddedContentId(segment) {
     return PHYSICAL_SEGMENT_PATTERN.test(segment);
 }
 /**
- * Check if a path appears to be a physical path (contains embedded content IDs).
- *
- * Physical paths have the format:
- * - `content/posts.abc123/post.hello.def456.json`
- *
- * Logical paths do not have embedded IDs:
- * - `content/posts/hello` or `posts/hello`
- *
- * @param path - The path to check
- * @returns true if any segment contains an embedded content ID
+ * Whether any segment carries an embedded content ID:
+ * `content/posts.abc123/post.hello.def456.json` does, `content/posts/hello`
+ * does not.
+ * @internal Exported for tests.
  */
 export function looksLikePhysicalPath(path) {
     const segments = path.split('/');
     return segments.some(hasEmbeddedContentId);
 }
-/**
- * Check if a path appears to be a logical path (no embedded content IDs).
- *
- * @param path - The path to check
- * @returns true if no segments contain embedded content IDs
- */
+/** @internal Exported for tests. */
 export function looksLikeLogicalPath(path) {
     return !looksLikePhysicalPath(path);
 }
 /**
- * Validate and cast a string to LogicalPath.
- *
- * Use this at API boundaries to validate incoming path strings
- * and cast them to the branded LogicalPath type.
- *
- * @param path - The path string to validate
- * @returns Object with success flag and either the typed path or an error
- *
- * @example
- * ```ts
- * const result = parseLogicalPath(params.collectionPath)
- * if (!result.ok) {
- *   return { ok: false, status: 400, error: result.error }
- * }
- * const collectionPath: LogicalPath = result.path
- * ```
+ * Validate an incoming path string at an API boundary and cast it to the
+ * branded LogicalPath type.
  */
 export function parseLogicalPath(path) {
-    // Basic validation
     if (!path || typeof path !== 'string') {
         return { ok: false, error: 'Path is required' };
     }
-    // Normalize backslashes to forward slashes (consistent with parsePermissionPath)
+    // One separator in the branded value, as in parsePermissionPath.
     const normalized = path.replace(/\\/g, '/');
-    // Security check
     if (hasTraversalSequence(normalized)) {
         return { ok: false, error: 'Path contains traversal sequence' };
     }
-    // Check it's not a physical path
     if (looksLikePhysicalPath(normalized)) {
         return {
             ok: false,
@@ -152,26 +96,19 @@ export function parseLogicalPath(path) {
     return { ok: true, path: normalized };
 }
 /**
- * Validate and cast a string to PhysicalPath.
- *
- * Use this at API boundaries to validate incoming path strings
- * and cast them to the branded PhysicalPath type.
- *
- * @param path - The path string to validate
- * @returns Object with success flag and either the typed path or an error
+ * Validate an incoming path string at an API boundary and cast it to the
+ * branded PhysicalPath type.
+ * @internal Exported for tests.
  */
 export function parsePhysicalPath(path) {
-    // Basic validation
     if (!path || typeof path !== 'string') {
         return { ok: false, error: 'Path is required' };
     }
-    // Normalize backslashes to forward slashes (consistent with parseLogicalPath)
+    // One separator in the branded value, as in parseLogicalPath.
     const normalized = path.replace(/\\/g, '/');
-    // Security check
     if (hasTraversalSequence(normalized)) {
         return { ok: false, error: 'Path contains traversal sequence' };
     }
-    // Check it looks like a physical path
     if (!looksLikePhysicalPath(normalized)) {
         return {
             ok: false,
@@ -180,31 +117,10 @@ export function parsePhysicalPath(path) {
     }
     return { ok: true, path: normalized };
 }
-/**
- * Check if a string is a valid 12-character content ID.
- *
- * @param id - The string to check
- * @returns true if valid Base58 12-char ID
- */
 export function isValidContentId(id) {
     return CONTENT_ID_PATTERN.test(id);
 }
-/**
- * Parse and validate a ContentId from a string.
- * Validates Base58 format and 12-character length.
- *
- * @param id - The string to validate
- * @returns Object with success flag and either the typed ID or an error
- *
- * @example
- * ```ts
- * const result = parseContentId(fileId)
- * if (!result.ok) {
- *   throw new Error(result.error)
- * }
- * const contentId: ContentId = result.id
- * ```
- */
+/** Validate a string as a 12-character Base58 ContentId and cast it. */
 export function parseContentId(id) {
     if (!id || typeof id !== 'string') {
         return { ok: false, error: 'Content ID is required' };
@@ -217,22 +133,7 @@ export function parseContentId(id) {
     }
     return { ok: true, id: id };
 }
-/**
- * Parse and validate a BranchName.
- * Checks git branch naming rules.
- *
- * @param name - The branch name to validate
- * @returns Object with success flag and either the typed name or an error
- *
- * @example
- * ```ts
- * const result = parseBranchName(params.branch)
- * if (!result.ok) {
- *   return { ok: false, status: 400, error: result.error }
- * }
- * const branchName: BranchName = result.name
- * ```
- */
+/** Validate a branch name against git's ref rules and cast it to BranchName. */
 export function parseBranchName(name) {
     if (!name || typeof name !== 'string') {
         return { ok: false, error: 'Branch name is required' };
@@ -241,7 +142,6 @@ export function parseBranchName(name) {
     if (name.length > 250) {
         return { ok: false, error: 'Branch name too long (max 250 characters)' };
     }
-    // Git branch name rules
     if (name.includes('..')) {
         return { ok: false, error: 'Branch name cannot contain ".."' };
     }
@@ -257,16 +157,14 @@ export function parseBranchName(name) {
     if (name.startsWith('-')) {
         return { ok: false, error: 'Branch name cannot start with "-"' };
     }
-    // Additional git restrictions
     if (name.startsWith('.') || name.endsWith('.')) {
         return { ok: false, error: 'Branch name cannot start or end with a dot' };
     }
     if (name.includes('@{')) {
         return { ok: false, error: 'Branch name cannot contain "@{"' };
     }
-    // Bare reserved refs: "HEAD" and "@" are ambiguous shorthand for the
-    // current ref, not real branch names (still allow names that merely
-    // contain these as a substring, e.g. "release-HEAD" or "HEADer").
+    // Bare "HEAD" and "@" are ambiguous shorthand for the current ref, not real
+    // branch names. Names merely containing them ("release-HEAD") stay legal.
     if (name === 'HEAD' || name === '@') {
         return { ok: false, error: 'Branch name cannot be the reserved ref "HEAD" or "@"' };
     }
@@ -280,22 +178,7 @@ export function parseBranchName(name) {
     }
     return { ok: true, name: name };
 }
-/**
- * Parse and validate a slug (collection or entry).
- * Validates format and length constraints.
- *
- * @param slug - The slug to validate
- * @returns Object with success flag and either the typed slug or an error
- *
- * @example
- * ```ts
- * const result = parseSlug(params.slug)
- * if (!result.ok) {
- *   return { ok: false, status: 400, error: result.error }
- * }
- * const slug: Slug = result.slug
- * ```
- */
+/** Validate a collection or entry slug and cast it to Slug. */
 export function parseSlug(slug) {
     if (!slug) {
         return {
@@ -307,7 +190,6 @@ export function parseSlug(slug) {
     if (slug.length > 64) {
         return { ok: false, error: 'Slug too long (max 64 characters)' };
     }
-    // Check for path separators and traversal
     if (slug.includes('/') || slug.includes('\\')) {
         return {
             ok: false,