@stati/core 1.0.0 → 1.2.0

package/dist/core/invalidate.js

@@ -1,7 +1,324 @@
+import { join } from 'path';
+import { loadCacheManifest, saveCacheManifest } from './isg/manifest.js';
+/**
+ * Parses an invalidation query string into individual query terms.
+ * Supports space-separated values and quoted strings.
+ *
+ * @param query - The query string to parse
+ * @returns Array of parsed query terms
+ *
+ * @example
+ * ```typescript
+ * parseInvalidationQuery('tag:blog path:/posts') // ['tag:blog', 'path:/posts']
+ * parseInvalidationQuery('"tag:my tag" path:"/my path"') // ['tag:my tag', 'path:/my path']
+ * ```
+ */
+export function parseInvalidationQuery(query) {
+    const terms = [];
+    let current = '';
+    let inQuotes = false;
+    let quoteChar = '';
+    for (let i = 0; i < query.length; i++) {
+        const char = query[i];
+        if (char === '"' || char === "'") {
+            if (!inQuotes) {
+                inQuotes = true;
+                quoteChar = char;
+            }
+            else if (char === quoteChar) {
+                inQuotes = false;
+                quoteChar = '';
+            }
+            else {
+                current += char;
+            }
+        }
+        else if (char === ' ' && !inQuotes) {
+            if (current.trim()) {
+                terms.push(current.trim());
+                current = '';
+            }
+        }
+        else {
+            current += char;
+        }
+    }
+    if (current.trim()) {
+        terms.push(current.trim());
+    }
+    return terms;
+}
+/**
+ * Checks if a cache entry matches a specific invalidation term.
+ *
+ * @param entry - Cache entry to check
+ * @param path - The page path for this entry
+ * @param term - Invalidation term to match against
+ * @returns True if the entry matches the term
+ *
+ * @example
+ * ```typescript
+ * matchesInvalidationTerm(entry, '/blog/post-1', 'tag:blog') // true if entry has 'blog' tag
+ * matchesInvalidationTerm(entry, '/blog/post-1', 'path:/blog') // true (path prefix match)
+ * ```
+ */
+export function matchesInvalidationTerm(entry, path, term) {
+    // Parse term into type and value
+    if (term.includes(':')) {
+        const [type, value] = term.split(':', 2);
+        // Ensure both type and value exist
+        if (!type || !value) {
+            return false;
+        }
+        switch (type.toLowerCase()) {
+            case 'tag':
+                return entry.tags.includes(value);
+            case 'path':
+                // Support both exact path match and prefix match
+                return path === value || path.startsWith(value);
+            case 'glob':
+                // Simple glob pattern matching for paths
+                return matchesGlob(path, value);
+            case 'age':
+                // Time-based invalidation: age:3months, age:1week, age:30days
+                return matchesAge(entry, value);
+            default:
+                console.warn(`Unknown invalidation term type: ${type}`);
+                return false;
+        }
+    }
+    else {
+        // Plain term - search in tags and path
+        return entry.tags.some((tag) => tag.includes(term)) || path.includes(term);
+    }
+}
+/**
+ * Simple glob pattern matching for paths.
+ * Supports * and ** wildcards.
+ *
+ * @param path - Path to test
+ * @param pattern - Glob pattern
+ * @returns True if path matches pattern
+ */
+function matchesGlob(path, pattern) {
+    try {
+        // Convert glob pattern to regex by processing character by character
+        // This avoids the magic string replacement issue
+        const regex = globToRegex(pattern);
+        return regex.test(path);
+    }
+    catch {
+        console.warn(`Invalid glob pattern: ${pattern}`);
+        return false;
+    }
+}
+/**
+ * Converts a glob pattern to a regular expression.
+ * Processes the pattern character by character to avoid placeholder conflicts.
+ *
+ * @param pattern - Glob pattern to convert
+ * @returns Regular expression that matches the glob pattern
+ */
+function globToRegex(pattern) {
+    let regexStr = '^';
+    let i = 0;
+    while (i < pattern.length) {
+        const char = pattern[i];
+        switch (char) {
+            case '*':
+                if (i + 1 < pattern.length && pattern[i + 1] === '*') {
+                    // Handle ** (matches any path including subdirectories)
+                    if (i + 2 < pattern.length && pattern[i + 2] === '/') {
+                        // **/ pattern - matches zero or more directories
+                        regexStr += '(?:.*/)?';
+                        i += 3;
+                    }
+                    else if (i + 2 === pattern.length) {
+                        // ** at end - matches everything
+                        regexStr += '.*';
+                        i += 2;
+                    }
+                    else {
+                        // ** not followed by / or end - treat as single *
+                        regexStr += '[^/]*';
+                        i += 1;
+                    }
+                }
+                else {
+                    // Single * matches any characters except path separator
+                    regexStr += '[^/]*';
+                    i += 1;
+                }
+                break;
+            case '?':
+                // ? matches any single character except path separator
+                regexStr += '[^/]';
+                i += 1;
+                break;
+            case '[': {
+                // Handle character classes - find the closing bracket
+                let closeIndex = i + 1;
+                while (closeIndex < pattern.length && pattern[closeIndex] !== ']') {
+                    closeIndex++;
+                }
+                if (closeIndex >= pattern.length) {
+                    // No closing bracket found - this creates an invalid regex
+                    // Just add the character and let the regex constructor throw an error
+                    regexStr += char;
+                    i += 1;
+                }
+                else {
+                    // Valid character class - copy it as-is
+                    regexStr += pattern.slice(i, closeIndex + 1);
+                    i = closeIndex + 1;
+                }
+                break;
+            }
+            case '.':
+            case '+':
+            case '^':
+            case '$':
+            case '(':
+            case ')':
+            case ']':
+            case '{':
+            case '}':
+            case '|':
+            case '\\':
+                // Escape regex special characters
+                regexStr += '\\' + char;
+                i += 1;
+                break;
+            default:
+                // Regular character
+                regexStr += char;
+                i += 1;
+                break;
+        }
+    }
+    regexStr += '$';
+    return new RegExp(regexStr);
+}
+/**
+ * Checks if a cache entry matches an age-based invalidation term.
+ * Supports various time units: days, weeks, months, years.
+ *
+ * @param entry - Cache entry to check
+ * @param ageValue - Age specification (e.g., "3months", "1week", "30days")
+ * @returns True if the entry is younger than the specified age
+ *
+ * @example
+ * ```typescript
+ * matchesAge(entry, "3months") // true if rendered within the last 3 months
+ * matchesAge(entry, "1week")   // true if rendered within the last 1 week
+ * ```
+ */
+function matchesAge(entry, ageValue) {
+    const now = new Date();
+    const renderedAt = new Date(entry.renderedAt);
+    // Parse age value (e.g., "3months", "1week", "30days")
+    const match = ageValue.match(/^(\d+)(days?|weeks?|months?|years?)$/i);
+    if (!match || !match[1] || !match[2]) {
+        console.warn(`Invalid age format: ${ageValue}. Use format like "3months", "1week", "30days"`);
+        return false;
+    }
+    const numStr = match[1];
+    const unit = match[2];
+    const num = parseInt(numStr, 10);
+    if (isNaN(num) || num <= 0) {
+        console.warn(`Invalid age number: ${numStr}`);
+        return false;
+    }
+    // Calculate cutoff date
+    const cutoffDate = new Date(now);
+    switch (unit.toLowerCase()) {
+        case 'day':
+        case 'days':
+            cutoffDate.setDate(cutoffDate.getDate() - num);
+            break;
+        case 'week':
+        case 'weeks':
+            cutoffDate.setDate(cutoffDate.getDate() - num * 7);
+            break;
+        case 'month':
+        case 'months':
+            cutoffDate.setMonth(cutoffDate.getMonth() - num);
+            break;
+        case 'year':
+        case 'years':
+            cutoffDate.setFullYear(cutoffDate.getFullYear() - num);
+            break;
+        default:
+            console.warn(`Unknown time unit: ${unit}`);
+            return false;
+    }
+    // Entry matches if it was rendered after the cutoff date (i.e., younger than specified age)
+    return renderedAt > cutoffDate;
+}
+/**
+ * Invalidates cache entries based on a query string.
+ * Supports tag-based, path-based, pattern-based, and time-based invalidation.
+ *
+ * @param query - Invalidation query string, or undefined to clear all cache
+ * @returns Promise resolving to invalidation result
+ *
+ * @example
+ * ```typescript
+ * // Invalidate all pages with 'blog' tag
+ * await invalidate('tag:blog');
+ *
+ * // Invalidate specific path
+ * await invalidate('path:/about');
+ *
+ * // Invalidate content younger than 3 months
+ * await invalidate('age:3months');
+ *
+ * // Invalidate multiple criteria
+ * await invalidate('tag:blog age:1week');
+ *
+ * // Clear entire cache
+ * await invalidate();
+ * ```
+ */
 export async function invalidate(query) {
-    // TODO This will be implemented in Milestone 4 (ISG)
-    console.log('Invalidate functionality will be available in a future release');
-    if (query) {
-        console.log(`Query: ${query}`);
+    const cacheDir = join(process.cwd(), '.stati');
+    // Load existing cache manifest
+    let cacheManifest = await loadCacheManifest(cacheDir);
+    if (!cacheManifest) {
+        // No cache to invalidate
+        return {
+            invalidatedCount: 0,
+            invalidatedPaths: [],
+            clearedAll: false,
+        };
+    }
+    const invalidatedPaths = [];
+    if (!query || query.trim() === '') {
+        // Clear entire cache
+        invalidatedPaths.push(...Object.keys(cacheManifest.entries));
+        cacheManifest.entries = {};
+        await saveCacheManifest(cacheDir, cacheManifest);
+        return {
+            invalidatedCount: invalidatedPaths.length,
+            invalidatedPaths,
+            clearedAll: true,
+        };
+    }
+    // Parse query terms
+    const terms = parseInvalidationQuery(query.trim());
+    // Find entries that match any of the terms
+    for (const [path, entry] of Object.entries(cacheManifest.entries)) {
+        const shouldInvalidate = terms.some((term) => matchesInvalidationTerm(entry, path, term));
+        if (shouldInvalidate) {
+            delete cacheManifest.entries[path];
+            invalidatedPaths.push(path);
+        }
     }
+    // Save updated cache manifest
+    await saveCacheManifest(cacheDir, cacheManifest);
+    return {
+        invalidatedCount: invalidatedPaths.length,
+        invalidatedPaths,
+        clearedAll: false,
+    };
 }

package/dist/core/isg/build-lock.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Build lock information stored in the lock file.
+ */
+interface BuildLock {
+    pid: number;
+    timestamp: string;
+    hostname?: string;
+}
+/**
+ * Manages build process locking to prevent concurrent Stati builds from corrupting cache.
+ * Uses a simple file-based locking mechanism with process ID tracking.
+ */
+export declare class BuildLockManager {
+    private lockPath;
+    private isLocked;
+    constructor(cacheDir: string);
+    /**
+     * Attempts to acquire a build lock.
+     * Throws an error if another build process is already running.
+     *
+     * @param options - Lock acquisition options
+     * @param options.force - Force acquire lock even if another process holds it
+     * @param options.timeout - Maximum time to wait for lock in milliseconds
+     * @throws {Error} When lock cannot be acquired
+     *
+     * @example
+     * ```typescript
+     * const lockManager = new BuildLockManager('.stati');
+     * try {
+     *   await lockManager.acquireLock();
+     *   // Proceed with build
+     * } finally {
+     *   await lockManager.releaseLock();
+     * }
+     * ```
+     */
+    acquireLock(options?: {
+        force?: boolean;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Releases the build lock if this process owns it.
+     *
+     * @example
+     * ```typescript
+     * await lockManager.releaseLock();
+     * ```
+     */
+    releaseLock(): Promise<void>;
+    /**
+     * Checks if a build lock is currently held by any process.
+     *
+     * @returns True if a lock exists and the owning process is running
+     *
+     * @example
+     * ```typescript
+     * if (await lockManager.isLocked()) {
+     *   console.log('Another build is in progress');
+     * }
+     * ```
+     */
+    isLockHeld(): Promise<boolean>;
+    /**
+     * Gets information about the current lock holder.
+     *
+     * @returns Lock information or null if no lock exists
+     */
+    getLockInfo(): Promise<BuildLock | null>;
+    /**
+     * Force removes the lock file without checking ownership.
+     * Should only be used in error recovery scenarios.
+     */
+    private forceRemoveLock;
+    /**
+     * Creates a new lock file with current process information.
+     */
+    private createLockFile;
+    /**
+     * Reads and parses the lock file.
+     */
+    private readLockFile;
+    /**
+     * Checks if a process with the given PID is currently running.
+     */
+    private isProcessRunning;
+    /**
+     * Gets the hostname for lock identification.
+     */
+    private getHostname;
+    /**
+     * Simple sleep utility for polling delays.
+     */
+    private sleep;
+}
+/**
+ * Convenience function to safely execute a build with automatic lock management.
+ *
+ * @param cacheDir - Path to the cache directory
+ * @param buildFn - Function to execute while holding the lock
+ * @param options - Lock options
+ * @returns Result of the build function
+ *
+ * @example
+ * ```typescript
+ * const result = await withBuildLock('.stati', async () => {
+ *   // Your build logic here
+ *   return await performBuild();
+ * });
+ * ```
+ */
+export declare function withBuildLock<T>(cacheDir: string, buildFn: () => Promise<T>, options?: {
+    force?: boolean;
+    timeout?: number;
+}): Promise<T>;
+export {};
+//# sourceMappingURL=build-lock.d.ts.map

package/dist/core/isg/build-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-lock.d.ts","sourceRoot":"","sources":["../../../src/core/isg/build-lock.ts"],"names":[],"mappings":"AAYA;;GAEG;AACH,UAAU,SAAS;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAS;gBAEb,QAAQ,EAAE,MAAM;IAI5B;;;;;;;;;;;;;;;;;;;OAmBG;IACG,WAAW,CAAC,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAoDrF;;;;;;;OAOG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAqBlC;;;;;;;;;;;OAWG;IACG,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IAiBpC;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAY9C;;;OAGG;YACW,eAAe;IAQ7B;;OAEG;YACW,cAAc;IAW5B;;OAEG;YACW,YAAY;IAS1B;;OAEG;YACW,gBAAgB;IAY9B;;OAEG;IACH,OAAO,CAAC,WAAW;IAQnB;;OAEG;IACH,OAAO,CAAC,KAAK;CAGd;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAClD,OAAO,CAAC,CAAC,CAAC,CASZ"}

package/dist/core/isg/build-lock.js

@@ -0,0 +1,243 @@
+import fse from 'fs-extra';
+const { writeFile, readFile, pathExists, remove } = fse;
+import { join } from 'path';
+import { hostname } from 'os';
+/**
+ * Manages build process locking to prevent concurrent Stati builds from corrupting cache.
+ * Uses a simple file-based locking mechanism with process ID tracking.
+ */
+export class BuildLockManager {
+    lockPath;
+    isLocked = false;
+    constructor(cacheDir) {
+        this.lockPath = join(cacheDir, '.build-lock');
+    }
+    /**
+     * Attempts to acquire a build lock.
+     * Throws an error if another build process is already running.
+     *
+     * @param options - Lock acquisition options
+     * @param options.force - Force acquire lock even if another process holds it
+     * @param options.timeout - Maximum time to wait for lock in milliseconds
+     * @throws {Error} When lock cannot be acquired
+     *
+     * @example
+     * ```typescript
+     * const lockManager = new BuildLockManager('.stati');
+     * try {
+     *   await lockManager.acquireLock();
+     *   // Proceed with build
+     * } finally {
+     *   await lockManager.releaseLock();
+     * }
+     * ```
+     */
+    async acquireLock(options = {}) {
+        const { force = false, timeout = 30000 } = options;
+        const startTime = Date.now();
+        while (Date.now() - startTime < timeout) {
+            try {
+                // Check if lock file exists
+                if (await pathExists(this.lockPath)) {
+                    const existingLock = await this.readLockFile();
+                    if (existingLock && !force) {
+                        // Check if the process is still running
+                        if (await this.isProcessRunning(existingLock.pid)) {
+                            // Wait a bit and try again
+                            await this.sleep(1000);
+                            continue;
+                        }
+                        else {
+                            // Process is dead, remove stale lock
+                            console.warn(`Removing stale build lock (PID ${existingLock.pid} no longer running)`);
+                            await this.forceRemoveLock();
+                        }
+                    }
+                    else if (force) {
+                        console.warn('Force acquiring build lock, removing existing lock');
+                        await this.forceRemoveLock();
+                    }
+                }
+                // Try to create the lock
+                await this.createLockFile();
+                this.isLocked = true;
+                return;
+            }
+            catch (error) {
+                const nodeError = error;
+                if (nodeError.code === 'EEXIST') {
+                    // Another process created the lock between our check and creation
+                    await this.sleep(1000);
+                    continue;
+                }
+                throw new Error(`Failed to acquire build lock: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        throw new Error(`Build lock acquisition timed out after ${timeout}ms. ` +
+            `Another Stati build process may be running. Use --force to override.`);
+    }
+    /**
+     * Releases the build lock if this process owns it.
+     *
+     * @example
+     * ```typescript
+     * await lockManager.releaseLock();
+     * ```
+     */
+    async releaseLock() {
+        if (!this.isLocked) {
+            return;
+        }
+        try {
+            // Verify we still own the lock before removing it
+            const currentLock = await this.readLockFile();
+            if (currentLock && currentLock.pid === process.pid) {
+                await remove(this.lockPath);
+            }
+        }
+        catch (error) {
+            // Don't throw on release errors, just warn
+            console.warn(`Warning: Failed to release build lock: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        finally {
+            this.isLocked = false;
+        }
+    }
+    /**
+     * Checks if a build lock is currently held by any process.
+     *
+     * @returns True if a lock exists and the owning process is running
+     *
+     * @example
+     * ```typescript
+     * if (await lockManager.isLocked()) {
+     *   console.log('Another build is in progress');
+     * }
+     * ```
+     */
+    async isLockHeld() {
+        try {
+            if (!(await pathExists(this.lockPath))) {
+                return false;
+            }
+            const lock = await this.readLockFile();
+            if (!lock) {
+                return false;
+            }
+            return await this.isProcessRunning(lock.pid);
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Gets information about the current lock holder.
+     *
+     * @returns Lock information or null if no lock exists
+     */
+    async getLockInfo() {
+        try {
+            if (!(await pathExists(this.lockPath))) {
+                return null;
+            }
+            return await this.readLockFile();
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Force removes the lock file without checking ownership.
+     * Should only be used in error recovery scenarios.
+     */
+    async forceRemoveLock() {
+        try {
+            await remove(this.lockPath);
+        }
+        catch {
+            // Ignore errors when force removing
+        }
+    }
+    /**
+     * Creates a new lock file with current process information.
+     */
+    async createLockFile() {
+        const lockInfo = {
+            pid: process.pid,
+            timestamp: new Date().toISOString(),
+            hostname: this.getHostname(),
+        };
+        // Use 'wx' flag to create file exclusively (fails if exists)
+        await writeFile(this.lockPath, JSON.stringify(lockInfo, null, 2), { flag: 'wx' });
+    }
+    /**
+     * Reads and parses the lock file.
+     */
+    async readLockFile() {
+        try {
+            const content = await readFile(this.lockPath, 'utf-8');
+            return JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Checks if a process with the given PID is currently running.
+     */
+    async isProcessRunning(pid) {
+        try {
+            // On Unix systems, sending signal 0 checks if process exists without affecting it
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (error) {
+            const nodeError = error;
+            // ESRCH means process doesn't exist
+            return nodeError.code !== 'ESRCH';
+        }
+    }
+    /**
+     * Gets the hostname for lock identification.
+     */
+    getHostname() {
+        try {
+            return hostname();
+        }
+        catch {
+            return 'unknown';
+        }
+    }
+    /**
+     * Simple sleep utility for polling delays.
+     */
+    sleep(ms) {
+        return new Promise((resolve) => global.setTimeout(resolve, ms));
+    }
+}
+/**
+ * Convenience function to safely execute a build with automatic lock management.
+ *
+ * @param cacheDir - Path to the cache directory
+ * @param buildFn - Function to execute while holding the lock
+ * @param options - Lock options
+ * @returns Result of the build function
+ *
+ * @example
+ * ```typescript
+ * const result = await withBuildLock('.stati', async () => {
+ *   // Your build logic here
+ *   return await performBuild();
+ * });
+ * ```
+ */
+export async function withBuildLock(cacheDir, buildFn, options = {}) {
+    const lockManager = new BuildLockManager(cacheDir);
+    try {
+        await lockManager.acquireLock(options);
+        return await buildFn();
+    }
+    finally {
+        await lockManager.releaseLock();
+    }
+}