@stati/core 1.20.0 → 1.20.2

package/dist/core/dev.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/core/dev.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAe,MAAM,EAAE,MAAM,mBAAmB,CAAC;AA2B7D,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;CACb;AAiXD,wBAAsB,eAAe,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,SAAS,CAAC,CAudxF"}
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/core/dev.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAe,MAAM,EAAE,MAAM,mBAAmB,CAAC;AA6B7D,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;CACb;AAuXD,wBAAsB,eAAe,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,SAAS,CAAC,CAgexF"}

package/dist/core/dev.js

@@ -1,5 +1,5 @@
 import { createServer } from 'node:http';
-import { join, extname, posix } from 'node:path';
+import { join, extname } from 'node:path';
 import { readFile } from 'node:fs/promises';
 import { WebSocketServer } from 'ws';
 import chokidar from 'chokidar';
@@ -9,7 +9,7 @@ import { loadConfig } from '../config/loader.js';
 import { loadCacheManifest, saveCacheManifest, computeNavigationHash } from './isg/index.js';
 import { loadContent } from './content.js';
 import { buildNavigation } from './navigation.js';
-import { resolveDevPaths, resolveCacheDir, resolvePrettyUrl, createErrorOverlay, parseErrorDetails, TemplateError, createFallbackLogger, mergeServerOptions, createTypeScriptWatcher, } from './utils/index.js';
+import { resolveDevPaths, resolveCacheDir, resolvePrettyUrl, createErrorOverlay, parseErrorDetails, TemplateError, createFallbackLogger, mergeServerOptions, createTypeScriptWatcher, normalizePathForComparison, isPathWithinDirectory, } from './utils/index.js';
 import { setEnv, getEnv } from '../env.js';
 import { DEFAULT_DEV_PORT, DEFAULT_DEV_HOST, TEMPLATE_EXTENSION, DEFAULT_OUT_DIR, } from '../constants.js';
 /**
@@ -180,7 +180,9 @@ async function performIncrementalRebuild(changedPath, eventType, configPath, sta
     }
 }
 /**
- * Handles template/partial file changes by invalidating affected pages
+ * Handles template/partial file changes by invalidating affected pages.
+ * Uses proper path normalization to ensure reliable matching between
+ * file watcher paths and cached dependency paths.
  */
 async function handleTemplateChange(templatePath, configPath, logger) {
     const cacheDir = resolveCacheDir();
@@ -197,16 +199,21 @@ async function handleTemplateChange(templatePath, configPath, logger) {
             });
             return;
         }
+        // Normalize the changed template path to absolute POSIX format for reliable comparison
+        // This handles cases where the watcher provides relative paths, Windows paths, or different
+        // path representations than what's stored in the cache manifest
+        const normalizedTemplatePath = normalizePathForComparison(templatePath);
         // Find pages that depend on this template
         let affectedPagesCount = 0;
-        const normalizedTemplatePath = posix.normalize(templatePath.replace(/\\/g, '/'));
         for (const [pagePath, entry] of Object.entries(cacheManifest.entries)) {
-            if (entry.deps.some((dep) => {
-                const normalizedDep = posix.normalize(dep.replace(/\\/g, '/'));
-                // Use endsWith for more precise matching to avoid false positives
-                return (normalizedDep === normalizedTemplatePath ||
-                    normalizedDep.endsWith('/' + normalizedTemplatePath));
-            })) {
+            // Check if any of the page's dependencies match the changed template
+            const hasMatchingDep = entry.deps.some((dep) => {
+                // Normalize the cached dependency path to the same format
+                const normalizedDep = normalizePathForComparison(dep);
+                // Direct path comparison - both paths are now in consistent format
+                return normalizedDep === normalizedTemplatePath;
+            });
+            if (hasMatchingDep) {
                 affectedPagesCount++;
                 // Remove from cache to force rebuild
                 delete cacheManifest.entries[pagePath];
@@ -439,6 +446,14 @@ export async function createDevServer(options = {}) {
             };
         }
         const originalFilePath = join(outDir, requestPath === '/' ? 'index.html' : requestPath);
+        // Security: Prevent path traversal attacks
+        if (!isPathWithinDirectory(outDir, originalFilePath)) {
+            return {
+                content: '403 - Forbidden',
+                mimeType: 'text/plain',
+                statusCode: 403,
+            };
+        }
         // Use the shared pretty URL resolver
         const { filePath, found } = await resolvePrettyUrl(outDir, requestPath, originalFilePath);
         if (!found || !filePath) {

package/dist/core/isg/deps.d.ts

@@ -7,14 +7,18 @@ export declare class CircularDependencyError extends Error {
     constructor(dependencyChain: string[], message: string);
 }
 /**
- * Tracks all template dependencies for a given page.
- * This includes the layout file and all accessible partials.
- * Includes circular dependency detection.
+ * Tracks template dependencies for a given page by parsing template content.
+ * Only includes templates that are actually referenced (via include, layout, or stati.partials calls).
+ * This provides accurate dependency tracking for ISG cache invalidation.
+ *
+ * The function recursively parses the layout template and all its dependencies to build
+ * the complete dependency tree. This ensures that changes to unused partials don't
+ * trigger unnecessary page rebuilds.
  *
  * @param page - The page model to track dependencies for
  * @param config - Stati configuration
- * @returns Array of absolute paths to dependency files
- * @throws {CircularDependencyError} When circular dependencies are detected
+ * @returns Array of absolute paths to actually-used template files (POSIX format)
+ * @throws {CircularDependencyError} When circular dependencies are detected in templates
  *
  * @example
  * ```typescript
@@ -29,20 +33,6 @@ export declare class CircularDependencyError extends Error {
  * ```
  */
 export declare function trackTemplateDependencies(page: PageModel, config: StatiConfig): Promise<string[]>;
-/**
- * Finds all partial dependencies for a given page path.
- * Searches up the directory hierarchy for _* folders containing .eta files.
- *
- * @param pagePath - Relative path to the page from srcDir
- * @param config - Stati configuration
- * @returns Array of absolute paths to partial files
- *
- * @example
- * ```typescript
- * const partials = await findPartialDependencies('blog/post.md', config);
- * ```
- */
-export declare function findPartialDependencies(pagePath: string, config: StatiConfig): Promise<string[]>;
 /**
  * Resolves a template name to its file path.
  * Used for explicit layout specifications in front matter.

package/dist/core/isg/deps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deps.d.ts","sourceRoot":"","sources":["../../../src/core/isg/deps.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGnE;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;aAE9B,eAAe,EAAE,MAAM,EAAE;gBAAzB,eAAe,EAAE,MAAM,EAAE,EACzC,OAAO,EAAE,MAAM;CAKlB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,MAAM,EAAE,CAAC,CAoCnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,MAAM,EAAE,CAAC,CAiDnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CASxB"}
+{"version":3,"file":"deps.d.ts","sourceRoot":"","sources":["../../../src/core/isg/deps.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGnE;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;aAE9B,eAAe,EAAE,MAAM,EAAE;gBAAzB,eAAe,EAAE,MAAM,EAAE,EACzC,OAAO,EAAE,MAAM;CAKlB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,MAAM,EAAE,CAAC,CA+CnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CASxB"}

package/dist/core/isg/deps.js

@@ -14,14 +14,18 @@ export class CircularDependencyError extends Error {
     }
 }
 /**
- * Tracks all template dependencies for a given page.
- * This includes the layout file and all accessible partials.
- * Includes circular dependency detection.
+ * Tracks template dependencies for a given page by parsing template content.
+ * Only includes templates that are actually referenced (via include, layout, or stati.partials calls).
+ * This provides accurate dependency tracking for ISG cache invalidation.
+ *
+ * The function recursively parses the layout template and all its dependencies to build
+ * the complete dependency tree. This ensures that changes to unused partials don't
+ * trigger unnecessary page rebuilds.
  *
  * @param page - The page model to track dependencies for
  * @param config - Stati configuration
- * @returns Array of absolute paths to dependency files
- * @throws {CircularDependencyError} When circular dependencies are detected
+ * @returns Array of absolute paths to actually-used template files (POSIX format)
+ * @throws {CircularDependencyError} When circular dependencies are detected in templates
  *
  * @example
  * ```typescript
@@ -45,75 +49,28 @@ export async function trackTemplateDependencies(page, config) {
     const srcDir = resolveSrcDir(config);
     const relativePath = relative(srcDir, page.sourcePath);
     // Track dependencies with circular detection
+    // The visited set will contain all templates that are actually used (not just accessible)
     const visited = new Set();
     const currentPath = new Set();
     // 1. Find the layout file that will be used for this page
     const layoutPath = await discoverLayout(relativePath, config, page.frontMatter.layout, isCollectionIndexPage(page));
     if (layoutPath) {
-        const absoluteLayoutPath = join(srcDir, layoutPath);
+        // Normalize to POSIX format for consistent manifest output across platforms
+        const absoluteLayoutPath = posix.join(srcDir.replace(/\\/g, '/'), layoutPath);
         deps.push(absoluteLayoutPath);
-        // Check for circular dependencies in layout chain
-        await detectCircularDependencies(absoluteLayoutPath, srcDir, visited, currentPath);
+        // Recursively traverse the template dependency tree
+        // This populates 'visited' with all actually-used templates (not just accessible ones)
+        await collectTemplateDependencies(absoluteLayoutPath, srcDir, visited, currentPath);
     }
-    // 2. Find all partials accessible to this page
-    const partialDeps = await findPartialDependencies(relativePath, config);
-    deps.push(...partialDeps);
-    return deps;
-}
-/**
- * Finds all partial dependencies for a given page path.
- * Searches up the directory hierarchy for _* folders containing .eta files.
- *
- * @param pagePath - Relative path to the page from srcDir
- * @param config - Stati configuration
- * @returns Array of absolute paths to partial files
- *
- * @example
- * ```typescript
- * const partials = await findPartialDependencies('blog/post.md', config);
- * ```
- */
-export async function findPartialDependencies(pagePath, config) {
-    // Early return if required config values are missing
-    if (!config.srcDir) {
-        console.warn('Config srcDir is missing, cannot find partial dependencies');
-        return [];
-    }
-    const deps = [];
-    const srcDir = resolveSrcDir(config);
-    // Get the directory of the current page
-    const pageDir = dirname(pagePath);
-    const pathSegments = pageDir === '.' ? [] : pageDir.split(/[/\\]/);
-    // Build list of directories to search (current dir up to root)
-    const dirsToSearch = [];
-    // Add directories from current up to root
-    if (pathSegments.length > 0) {
-        for (let i = pathSegments.length; i >= 0; i--) {
-            if (i === 0) {
-                dirsToSearch.push(''); // Root directory
-            }
-            else {
-                dirsToSearch.push(pathSegments.slice(0, i).join('/'));
-            }
-        }
-    }
-    else {
-        dirsToSearch.push(''); // Root directory only
-    }
-    // Search each directory for _* folders containing .eta files
-    for (const dir of dirsToSearch) {
-        const searchDir = dir ? join(srcDir, dir) : srcDir;
-        try {
-            // Find all .eta files in _* subdirectories
-            // Use posix.join to ensure forward slashes for glob patterns
-            const normalizedSearchDir = searchDir.replace(/\\/g, '/');
-            const pattern = posix.join(normalizedSearchDir, '_*/**/*.eta');
-            const partialFiles = await glob(pattern, { absolute: true });
-            deps.push(...partialFiles);
-        }
-        catch {
-            // Continue if directory doesn't exist or can't be read
-            continue;
+    // 2. Add all actually-used templates from the visited set
+    // Filter to only include underscore directories (partials/components)
+    // and normalize paths to POSIX format
+    for (const templatePath of visited) {
+        const normalizedPath = templatePath.replace(/\\/g, '/');
+        // Only add partials (files in directories starting with underscore) - layout is already added
+        // Use strict pattern to match /_dirname/ where dirname starts with underscore
+        if (/\/_[^/]+\//.test(normalizedPath)) {
+            deps.push(normalizedPath);
         }
     }
     return deps;
@@ -143,59 +100,63 @@ export async function resolveTemplatePath(layout, config) {
     return null;
 }
 /**
- * Detects circular dependencies in template includes/extends.
- * Uses DFS to traverse the dependency graph and detect cycles.
+ * Recursively collects all template dependencies by parsing template content.
+ * Only includes templates that are actually referenced (not just accessible).
+ * Uses DFS to traverse the dependency graph and detects circular references.
  *
- * @param templatePath - Absolute path to template file to check
+ * @param templatePath - Absolute path to template file to analyze
  * @param srcDir - Source directory for resolving relative template paths
- * @param visited - Set of all visited template paths (for optimization)
+ * @param visited - Set to track all visited templates (accumulated dependencies)
  * @param currentPath - Set of templates in current DFS path (for cycle detection)
  * @throws {CircularDependencyError} When a circular dependency is detected
  */
-async function detectCircularDependencies(templatePath, srcDir, visited, currentPath) {
-    // Skip if already processed
-    if (visited.has(templatePath)) {
-        return;
-    }
-    // Check for circular dependency
-    if (currentPath.has(templatePath)) {
-        const chain = Array.from(currentPath);
-        chain.push(templatePath);
+async function collectTemplateDependencies(templatePath, srcDir, visited, currentPath) {
+    // Normalize path for consistent tracking
+    const normalizedPath = templatePath.replace(/\\/g, '/');
+    // Check for circular dependency FIRST (before visited check)
+    // A circular dependency means we're visiting a template that's already in our current DFS path
+    // This must be checked before the visited check because a path in currentPath is always in visited
+    if (currentPath.has(normalizedPath)) {
+        const chain = [...currentPath, normalizedPath];
         throw new CircularDependencyError(chain, `Circular dependency detected in templates: ${chain.join(' -> ')}`);
     }
+    // Skip if already processed (but not in current path - those are handled above)
+    if (visited.has(normalizedPath)) {
+        return;
+    }
     // Check if template file exists
     if (!(await pathExists(templatePath))) {
-        // Don't treat missing files as circular dependencies
-        // They will be handled by the missing file error handling
         return;
     }
-    // Add to current path
-    currentPath.add(templatePath);
-    visited.add(templatePath);
+    // Add to tracking sets
+    currentPath.add(normalizedPath);
+    visited.add(normalizedPath);
     try {
         // Read template content to find includes/extends
         const content = await readFile(templatePath, 'utf-8');
         if (!content) {
-            return; // Skip if file doesn't exist
+            return;
         }
+        // Parse template to find referenced templates
         const dependencies = await parseTemplateDependencies(content, templatePath, srcDir);
-        // Recursively check dependencies
+        // Recursively collect dependencies
         for (const depPath of dependencies) {
-            await detectCircularDependencies(depPath, srcDir, visited, currentPath);
+            await collectTemplateDependencies(depPath, srcDir, visited, currentPath);
         }
     }
     catch (error) {
-        // If we can't read the file, don't treat it as a circular dependency
-        if (error instanceof Error && !error.message.includes('Circular dependency')) {
-            console.warn(`Warning: Could not read template ${templatePath}: ${error.message}`);
+        // Re-throw circular dependency errors - these are fatal
+        if (error instanceof CircularDependencyError) {
+            throw error;
         }
-        else {
-            throw error; // Re-throw circular dependency errors
+        // Log warning but continue - don't fail the entire build for template parsing issues
+        if (error instanceof Error) {
+            console.warn(`Warning: Could not parse template ${templatePath}: ${error.message}`);
         }
     }
     finally {
         // Remove from current path when backtracking
-        currentPath.delete(templatePath);
+        currentPath.delete(normalizedPath);
     }
 }
 /**
@@ -244,27 +205,52 @@ async function parseTemplateDependencies(content, templatePath, srcDir) {
             }
         }
     }
-    // Look for Stati callable partial patterns: stati.partials.name( or stati.partials['name'](
-    // This catches both direct property access and bracket notation with or without arguments
-    // Patterns allow for optional whitespace before the opening parenthesis
-    const callablePartialPatterns = [
-        /stati\.partials\.(\w+)\s*\(/g, // stati.partials.header( or stati.partials.header  (
-        /stati\.partials\[['"`]([^'"`]+)['"`]\]\s*\(/g, // stati.partials['header']( with whitespace
+    // Look for Stati partial patterns - both callable and non-callable
+    // Callable: stati.partials.name() or stati.partials['name']()
+    // Non-callable: stati.partials.name or stati.partials['name'] (used with <%~ %>)
+    const partialPatterns = [
+        // Callable patterns (with parentheses)
+        /stati\.partials\.(\w+)\s*\(/g, // stati.partials.header(
+        /stati\.partials\[['"`]([^'"`]+)['"`]\]\s*\(/g, // stati.partials['header'](
+        // Non-callable patterns (without parentheses, used in <%~ stati.partials.name %>)
+        // These patterns use lookaheads to distinguish between:
+        //   - stati.partials.name (partial reference, should match)
+        //   - stati.partials.name() (function call, should NOT match here - handled above)
+        //
+        // Pattern breakdown for dot notation: /stati\.partials\.(\w+)(?=\s*[%}\s]|$)(?!\s*\()/g
+        //   - stati\.partials\.  : Literal "stati.partials."
+        //   - (\w+)              : Capture partial name (letters, digits, underscore)
+        //   - (?=\s*[%}\s]|$)    : Positive lookahead - must be followed by whitespace, %, }, or end of string
+        //   - (?!\s*\()          : Negative lookahead - must NOT be followed by "(" (excludes function calls)
+        /stati\.partials\.(\w+)(?=\s*[%}\s]|$)(?!\s*\()/g,
+        // Pattern breakdown for bracket notation: /stati\.partials\[['"`]([^'"`]+)['"`]\](?=\s*[%}\s]|$)(?!\s*\()/g
+        //   - stati\.partials\[  : Literal "stati.partials["
+        //   - ['"`]              : Opening quote (single, double, or backtick)
+        //   - ([^'"`]+)          : Capture partial name (any chars except quotes)
+        //   - ['"`]\]            : Closing quote and bracket
+        //   - (?=\s*[%}\s]|$)    : Positive lookahead - must be followed by whitespace, %, }, or end of string
+        //   - (?!\s*\()          : Negative lookahead - must NOT be followed by "(" (excludes function calls)
+        /stati\.partials\[['"`]([^'"`]+)['"`]\](?=\s*[%}\s]|$)(?!\s*\()/g,
     ];
-    for (const pattern of callablePartialPatterns) {
+    // Use a Set to avoid duplicate partial names
+    const foundPartials = new Set();
+    for (const pattern of partialPatterns) {
         let match;
         while ((match = pattern.exec(content)) !== null) {
             const partialName = match[1];
             if (partialName) {
-                // Resolve the partial by searching for it in underscore directories
-                const partialFileName = `${partialName}${TEMPLATE_EXTENSION}`;
-                const resolvedPath = await resolveTemplatePathInternal(partialFileName, srcDir, templateDir);
-                if (resolvedPath) {
-                    dependencies.push(resolvedPath);
-                }
+                foundPartials.add(partialName);
             }
         }
     }
+    // Resolve each unique partial name
+    for (const partialName of foundPartials) {
+        const partialFileName = `${partialName}${TEMPLATE_EXTENSION}`;
+        const resolvedPath = await resolveTemplatePathInternal(partialFileName, srcDir, templateDir);
+        if (resolvedPath) {
+            dependencies.push(resolvedPath);
+        }
+    }
     return dependencies;
 }
 /**
@@ -320,7 +306,8 @@ async function resolveTemplatePathInternal(templateRef, srcDir, currentDir) {
             const pattern = posix.join(searchDir.replace(/\\/g, '/'), '_*', templateName);
             const matches = await glob(pattern, { absolute: true });
             if (matches.length > 0) {
-                return matches[0]; // Return first match
+                // Normalize to POSIX format for consistent cross-platform path handling
+                return matches[0].replace(/\\/g, '/');
             }
         }
         catch {

package/dist/core/isg/index.d.ts

@@ -9,7 +9,7 @@
 export { loadCacheManifest, saveCacheManifest, createEmptyManifest } from './manifest.js';
 export { shouldRebuildPage, createCacheEntry, updateCacheEntry } from './builder.js';
 export { BuildLockManager, withBuildLock } from './build-lock.js';
-export { CircularDependencyError, trackTemplateDependencies, findPartialDependencies, resolveTemplatePath, } from './deps.js';
+export { CircularDependencyError, trackTemplateDependencies, resolveTemplatePath } from './deps.js';
 export { computeContentHash, computeFileHash, computeInputsHash, computeNavigationHash, } from './hash.js';
 export { getSafeCurrentTime, parseSafeDate, computeEffectiveTTL, computeNextRebuildAt, isPageFrozen, applyAgingRules, } from './ttl.js';
 export { ISGConfigurationError, validateISGConfig, validatePageISGOverrides, extractNumericOverride, } from './validation.js';

package/dist/core/isg/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/isg/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAG1F,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrF,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGlE,OAAO,EACL,uBAAuB,EACvB,yBAAyB,EACzB,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,eAAe,GAChB,MAAM,UAAU,CAAC;AAGlB,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/isg/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAG1F,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrF,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGlE,OAAO,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAGpG,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,eAAe,GAChB,MAAM,UAAU,CAAC;AAGlB,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC"}

package/dist/core/isg/index.js

@@ -13,7 +13,7 @@ export { shouldRebuildPage, createCacheEntry, updateCacheEntry } from './builder
 // Build locking
 export { BuildLockManager, withBuildLock } from './build-lock.js';
 // Dependency tracking
-export { CircularDependencyError, trackTemplateDependencies, findPartialDependencies, resolveTemplatePath, } from './deps.js';
+export { CircularDependencyError, trackTemplateDependencies, resolveTemplatePath } from './deps.js';
 // Hash computation
 export { computeContentHash, computeFileHash, computeInputsHash, computeNavigationHash, } from './hash.js';
 // TTL and aging

package/dist/core/preview.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../src/core/preview.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAe,MAAM,mBAAmB,CAAC;AAU7D,MAAM,WAAW,oBAAoB;IACnC,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,0BAA0B;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sBAAsB;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;CACb;AAyBD;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,aAAa,CAAC,CAwJxB"}
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../src/core/preview.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAe,MAAM,mBAAmB,CAAC;AAW7D,MAAM,WAAW,oBAAoB;IACnC,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,0BAA0B;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sBAAsB;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;CACb;AAyBD;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,aAAa,CAAC,CAiKxB"}

package/dist/core/preview.js

@@ -2,7 +2,7 @@ import { createServer } from 'node:http';
 import { join, extname } from 'node:path';
 import { readFile } from 'node:fs/promises';
 import { loadConfig } from '../config/loader.js';
-import { resolveDevPaths, resolvePrettyUrl, createFallbackLogger, mergeServerOptions, } from './utils/index.js';
+import { resolveDevPaths, resolvePrettyUrl, createFallbackLogger, mergeServerOptions, isPathWithinDirectory, } from './utils/index.js';
 import { DEFAULT_PREVIEW_PORT, DEFAULT_DEV_HOST } from '../constants.js';
 /**
  * Loads and validates configuration for the preview server.
@@ -70,6 +70,14 @@ export async function createPreviewServer(options = {}) {
      */
     async function serveFile(requestPath) {
         const originalFilePath = join(outDir, requestPath === '/' ? 'index.html' : requestPath);
+        // Security: Prevent path traversal attacks
+        if (!isPathWithinDirectory(outDir, originalFilePath)) {
+            return {
+                content: '403 - Forbidden',
+                mimeType: 'text/plain',
+                statusCode: 403,
+            };
+        }
         // Use the shared pretty URL resolver
         const { filePath, found } = await resolvePrettyUrl(outDir, requestPath, originalFilePath);
         if (!found || !filePath) {

package/dist/core/utils/index.d.ts

@@ -3,7 +3,7 @@
  * @module core/utils
  */
 export { readFile, writeFile, pathExists, ensureDir, remove, copyFile, readdir, stat, } from './fs.utils.js';
-export { resolveSrcDir, resolveOutDir, resolveStaticDir, resolveCacheDir, resolveDevPaths, normalizeTemplatePath, resolveSrcPath, resolveOutPath, resolveStaticPath, } from './paths.utils.js';
+export { resolveSrcDir, resolveOutDir, resolveStaticDir, resolveCacheDir, resolveDevPaths, normalizeTemplatePath, resolveSrcPath, resolveOutPath, resolveStaticPath, normalizePathForComparison, isPathWithinDirectory, } from './paths.utils.js';
 export { discoverLayout, isCollectionIndexPage, getCollectionPathForPage, } from './template-discovery.utils.js';
 export { propValue } from './template.utils.js';
 export { slugify } from './slugify.utils.js';

package/dist/core/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/utils/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EACL,QAAQ,EACR,SAAS,EACT,UAAU,EACV,SAAS,EACT,MAAM,EACN,QAAQ,EACR,OAAO,EACP,IAAI,GACL,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,cAAc,EACd,cAAc,EACd,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGhD,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAG7C,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,wBAAwB,EACxB,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,2BAA2B,EAC3B,cAAc,EACd,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EAAE,6BAA6B,EAAE,MAAM,+BAA+B,CAAC;AAG9E,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAC3F,YAAY,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAGpE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAG/F,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAGxE,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACzE,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACjF,YAAY,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAG7D,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAGrD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAGpE,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAGrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAGzD,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAG1E,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/utils/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EACL,QAAQ,EACR,SAAS,EACT,UAAU,EACV,SAAS,EACT,MAAM,EACN,QAAQ,EACR,OAAO,EACP,IAAI,GACL,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,0BAA0B,EAC1B,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGhD,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAG7C,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,wBAAwB,EACxB,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,2BAA2B,EAC3B,cAAc,EACd,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EAAE,6BAA6B,EAAE,MAAM,+BAA+B,CAAC;AAG9E,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAC3F,YAAY,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAGpE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAG/F,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAGxE,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACzE,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACjF,YAAY,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAG7D,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAGrD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAGpE,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAGrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAGzD,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAG1E,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/core/utils/index.js

@@ -5,7 +5,7 @@
 // File system utilities
 export { readFile, writeFile, pathExists, ensureDir, remove, copyFile, readdir, stat, } from './fs.utils.js';
 // Path resolution utilities
-export { resolveSrcDir, resolveOutDir, resolveStaticDir, resolveCacheDir, resolveDevPaths, normalizeTemplatePath, resolveSrcPath, resolveOutPath, resolveStaticPath, } from './paths.utils.js';
+export { resolveSrcDir, resolveOutDir, resolveStaticDir, resolveCacheDir, resolveDevPaths, normalizeTemplatePath, resolveSrcPath, resolveOutPath, resolveStaticPath, normalizePathForComparison, isPathWithinDirectory, } from './paths.utils.js';
 // Template discovery utilities
 export { discoverLayout, isCollectionIndexPage, getCollectionPathForPage, } from './template-discovery.utils.js';
 // Template utilities

package/dist/core/utils/paths.utils.d.ts

@@ -64,4 +64,53 @@ export declare function resolveOutPath(config: StatiConfig, relativePath: string
  * @returns Absolute path
  */
 export declare function resolveStaticPath(config: StatiConfig, relativePath: string): string;
+/**
+ * Normalizes a file path to absolute POSIX format for consistent comparisons.
+ * Handles Windows paths, relative paths, and already-normalized paths.
+ *
+ * This utility ensures that paths from different sources (file watchers, cache manifest,
+ * glob results) can be reliably compared even when they use different representations.
+ *
+ * @param filePath - Path to normalize (can be relative or absolute, Windows or POSIX)
+ * @param basePath - Optional base path to resolve relative paths against (defaults to cwd)
+ * @returns Normalized absolute path with forward slashes and no trailing slashes
+ *
+ * @example
+ * ```typescript
+ * // Windows absolute path
+ * normalizePathForComparison('C:\\project\\site\\layout.eta')
+ * // Returns: 'C:/project/site/layout.eta'
+ *
+ * // Relative path
+ * normalizePathForComparison('site/layout.eta', '/project')
+ * // Returns: '/project/site/layout.eta'
+ *
+ * // Already POSIX path
+ * normalizePathForComparison('/project/site/layout.eta')
+ * // Returns: '/project/site/layout.eta'
+ * ```
+ */
+export declare function normalizePathForComparison(filePath: string, basePath?: string): string;
+/**
+ * Validates that a resolved path is safely within a base directory.
+ * This function prevents path traversal attacks by ensuring that a target path
+ * (which may contain `..` sequences or other traversal patterns) resolves to
+ * a location within the specified base directory.
+ *
+ * @param baseDir - The base directory that the target path must stay within
+ * @param targetPath - The target path to validate (can be relative or contain `..`)
+ * @returns `true` if the resolved target path is within the base directory, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * // Safe paths
+ * isPathWithinDirectory('/app/dist', '/app/dist/index.html')  // true
+ * isPathWithinDirectory('/app/dist', '/app/dist/pages/about.html')  // true
+ *
+ * // Path traversal attempts (returns false)
+ * isPathWithinDirectory('/app/dist', '/app/dist/../../../etc/passwd')  // false
+ * isPathWithinDirectory('/app/dist', '/../etc/passwd')  // false
+ * ```
+ */
+export declare function isPathWithinDirectory(baseDir: string, targetPath: string): boolean;
 //# sourceMappingURL=paths.utils.d.ts.map

package/dist/core/utils/paths.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.utils.d.ts","sourceRoot":"","sources":["../../../src/core/utils/paths.utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAQxD;;;GAGG;AAEH;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAE5D;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW;;;;EAMlD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAEhF;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAEhF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAEnF"}
+{"version":3,"file":"paths.utils.d.ts","sourceRoot":"","sources":["../../../src/core/utils/paths.utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAQxD;;;GAGG;AAEH;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAE5D;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW;;;;EAMlD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAEhF;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAEhF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAEnF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAuBtF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAYlF"}

package/dist/core/utils/paths.utils.js

@@ -1,4 +1,4 @@
-import { join, posix } from 'node:path';
+import { join, posix, resolve, sep } from 'node:path';
 import { DEFAULT_SRC_DIR, DEFAULT_OUT_DIR, DEFAULT_STATIC_DIR, CACHE_DIR_NAME, } from '../../constants.js';
 /**
  * File system path resolution utilities for Stati core.
@@ -83,3 +83,80 @@ export function resolveOutPath(config, relativePath) {
 export function resolveStaticPath(config, relativePath) {
     return join(resolveStaticDir(config), relativePath);
 }
+/**
+ * Normalizes a file path to absolute POSIX format for consistent comparisons.
+ * Handles Windows paths, relative paths, and already-normalized paths.
+ *
+ * This utility ensures that paths from different sources (file watchers, cache manifest,
+ * glob results) can be reliably compared even when they use different representations.
+ *
+ * @param filePath - Path to normalize (can be relative or absolute, Windows or POSIX)
+ * @param basePath - Optional base path to resolve relative paths against (defaults to cwd)
+ * @returns Normalized absolute path with forward slashes and no trailing slashes
+ *
+ * @example
+ * ```typescript
+ * // Windows absolute path
+ * normalizePathForComparison('C:\\project\\site\\layout.eta')
+ * // Returns: 'C:/project/site/layout.eta'
+ *
+ * // Relative path
+ * normalizePathForComparison('site/layout.eta', '/project')
+ * // Returns: '/project/site/layout.eta'
+ *
+ * // Already POSIX path
+ * normalizePathForComparison('/project/site/layout.eta')
+ * // Returns: '/project/site/layout.eta'
+ * ```
+ */
+export function normalizePathForComparison(filePath, basePath) {
+    // Convert backslashes to forward slashes for Windows compatibility
+    let normalized = filePath.replace(/\\/g, '/');
+    // Resolve to absolute path if relative
+    // Check if path is already absolute (starts with / or drive letter)
+    const isAbsolute = normalized.startsWith('/') || /^[a-zA-Z]:/.test(normalized);
+    if (!isAbsolute) {
+        const base = basePath || process.cwd();
+        // Use the already-normalized path to avoid reintroducing backslashes
+        normalized = join(base, normalized).replace(/\\/g, '/');
+    }
+    // Use posix.normalize to clean up any '..' or '.' segments and remove redundant separators
+    normalized = posix.normalize(normalized);
+    // Remove trailing slash (except for root path)
+    if (normalized.length > 1 && normalized.endsWith('/')) {
+        normalized = normalized.slice(0, -1);
+    }
+    return normalized;
+}
+/**
+ * Validates that a resolved path is safely within a base directory.
+ * This function prevents path traversal attacks by ensuring that a target path
+ * (which may contain `..` sequences or other traversal patterns) resolves to
+ * a location within the specified base directory.
+ *
+ * @param baseDir - The base directory that the target path must stay within
+ * @param targetPath - The target path to validate (can be relative or contain `..`)
+ * @returns `true` if the resolved target path is within the base directory, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * // Safe paths
+ * isPathWithinDirectory('/app/dist', '/app/dist/index.html')  // true
+ * isPathWithinDirectory('/app/dist', '/app/dist/pages/about.html')  // true
+ *
+ * // Path traversal attempts (returns false)
+ * isPathWithinDirectory('/app/dist', '/app/dist/../../../etc/passwd')  // false
+ * isPathWithinDirectory('/app/dist', '/../etc/passwd')  // false
+ * ```
+ */
+export function isPathWithinDirectory(baseDir, targetPath) {
+    // Resolve both paths to absolute paths with all `..` and `.` resolved
+    const resolvedBase = resolve(baseDir);
+    const resolvedTarget = resolve(targetPath);
+    // Normalize the base directory to ensure proper prefix matching
+    // Adding sep ensures '/app/dist' doesn't match '/app/dist-other'
+    const normalizedBase = resolvedBase.endsWith(sep) ? resolvedBase : resolvedBase + sep;
+    // Check if the resolved target starts with the normalized base
+    // We also allow exact match (resolvedTarget === resolvedBase) for the root
+    return resolvedTarget === resolvedBase || resolvedTarget.startsWith(normalizedBase);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stati/core",
-  "version": "1.20.0",
+  "version": "1.20.2",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",