@eddacraft/anvil-runtime 0.1.0

package/LICENSE

@@ -0,0 +1,14 @@
+Copyright (c) 2026 EddaCraft. All rights reserved.
+
+PROPRIETARY AND CONFIDENTIAL
+
+This software and associated documentation files (the "Software") are the
+exclusive property of EddaCraft. Unauthorised copying, modification,
+distribution, or use of this Software, via any medium, is strictly prohibited
+without the express written permission of EddaCraft.
+
+The Software is provided for evaluation and testing purposes only to authorised
+beta testers. No licence is granted to use, copy, modify, or distribute the
+Software for any other purpose.
+
+For licensing enquiries, contact: legal@eddacraft.com

package/dist/cache/cache-key.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Cache key generation utilities
+ */
+import type { GateCacheKeyInput } from './types.js';
+import type { GateCheck } from '../types/gate.types.js';
+/**
+ * Generate a deterministic cache key for gate check results
+ *
+ * Key format: gate:check:{check_name}:{combined_hash}
+ * Where combined_hash = SHA256(plan_hash + config_hash + workspace_root + extra)
+ */
+export declare function generateCacheKey(input: GateCacheKeyInput): string;
+/**
+ * Generate a hash for check configuration
+ * Used to invalidate cache when config changes
+ */
+export declare function hashCheckConfig(config: Record<string, unknown>): string;
+/**
+ * Generate a hash for the full gate configuration
+ * Used to invalidate all caches when global config changes
+ */
+export declare function hashGateConfig(checks: GateCheck[]): string;
+/**
+ * Generate an input hash for cache validation
+ * This hash captures all inputs that affect the cache result
+ */
+export declare function generateInputHash(input: GateCacheKeyInput): string;
+/**
+ * Parse a cache key into its components
+ */
+export declare function parseCacheKey(key: string): {
+    type: string;
+    subtype: string;
+    name: string;
+    hash: string;
+} | null;
+/**
+ * Generate a pattern for invalidating all cache entries for a check
+ */
+export declare function checkInvalidationPattern(checkName: string): string;
+/**
+ * Generate a pattern for invalidating all gate cache entries
+ */
+export declare function allGateInvalidationPattern(): string;
+//# sourceMappingURL=cache-key.d.ts.map

package/dist/cache/cache-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-key.d.ts","sourceRoot":"","sources":["../../src/cache/cache-key.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAKxD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAqBjE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAOvE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,CAgB1D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAIlE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,IAAI,CAaP;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;GAEG;AACH,wBAAgB,0BAA0B,IAAI,MAAM,CAEnD"}

package/dist/cache/cache-key.js

@@ -0,0 +1,135 @@
+/**
+ * Cache key generation utilities
+ */
+import { createHash } from 'node:crypto';
+import { createDebugger } from '@eddacraft/anvil-core';
+const debug = createDebugger('cache');
+/**
+ * Generate a deterministic cache key for gate check results
+ *
+ * Key format: gate:check:{check_name}:{combined_hash}
+ * Where combined_hash = SHA256(plan_hash + config_hash + workspace_root + extra)
+ */
+export function generateCacheKey(input) {
+    debug(`generateCacheKey: check=${input.check_name} plan_hash=${input.plan_hash}`);
+    const hash = createHash('sha256');
+    // Add all inputs in deterministic order
+    hash.update(input.plan_hash);
+    hash.update(input.config_hash);
+    hash.update(normaliseWorkspacePath(input.workspace_root));
+    // Add extra discriminators in sorted order
+    if (input.extra) {
+        const sortedKeys = Object.keys(input.extra).sort();
+        for (const key of sortedKeys) {
+            hash.update(`${key}:${input.extra[key]}`);
+        }
+    }
+    const combinedHash = hash.digest('hex').slice(0, 16);
+    const key = `gate:check:${input.check_name}:${combinedHash}`;
+    debug(`generateCacheKey: result=${key}`);
+    return key;
+}
+/**
+ * Generate a hash for check configuration
+ * Used to invalidate cache when config changes
+ */
+export function hashCheckConfig(config) {
+    const hash = createHash('sha256');
+    // Canonicalise JSON for deterministic hashing
+    hash.update(JSON.stringify(sortObjectKeys(config)));
+    const result = hash.digest('hex').slice(0, 16);
+    debug('hashCheckConfig', { keys: Object.keys(config), hash: result });
+    return result;
+}
+/**
+ * Generate a hash for the full gate configuration
+ * Used to invalidate all caches when global config changes
+ */
+export function hashGateConfig(checks) {
+    const hash = createHash('sha256');
+    // Only hash enabled checks and their configs
+    const enabledChecks = checks
+        .filter((c) => c.enabled)
+        .map((c) => ({
+        name: c.name,
+        config: c.config || {},
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    hash.update(JSON.stringify(enabledChecks));
+    const result = hash.digest('hex').slice(0, 16);
+    debug(`hashGateConfig: enabledChecks=${enabledChecks.length} hash=${result}`);
+    return result;
+}
+/**
+ * Generate an input hash for cache validation
+ * This hash captures all inputs that affect the cache result
+ */
+export function generateInputHash(input) {
+    const hash = createHash('sha256');
+    hash.update(JSON.stringify(sortObjectKeys(input)));
+    return hash.digest('hex');
+}
+/**
+ * Parse a cache key into its components
+ */
+export function parseCacheKey(key) {
+    const parts = key.split(':');
+    if (parts.length !== 4) {
+        debug(`parseCacheKey: invalid key format (expected 4 parts, got ${parts.length})`);
+        return null;
+    }
+    debug(`parseCacheKey: type=${parts[0]} name=${parts[2]}`);
+    return {
+        type: parts[0],
+        subtype: parts[1],
+        name: parts[2],
+        hash: parts[3],
+    };
+}
+/**
+ * Generate a pattern for invalidating all cache entries for a check
+ */
+export function checkInvalidationPattern(checkName) {
+    return `gate:check:${checkName}:*`;
+}
+/**
+ * Generate a pattern for invalidating all gate cache entries
+ */
+export function allGateInvalidationPattern() {
+    return 'gate:*';
+}
+/**
+ * Normalise workspace path for consistent cache keys
+ * - Removes trailing slashes
+ * - Converts backslashes to forward slashes (Windows)
+ * - Lowercases drive letters (Windows)
+ */
+function normaliseWorkspacePath(path) {
+    let normalised = path
+        // Convert backslashes to forward slashes
+        .replace(/\\/g, '/')
+        // Remove trailing slashes
+        .replace(/\/+$/, '');
+    // Lowercase Windows drive letters (C: -> c:)
+    if (/^[A-Z]:/.test(normalised)) {
+        normalised = normalised[0].toLowerCase() + normalised.slice(1);
+    }
+    return normalised;
+}
+/**
+ * Recursively sort object keys for deterministic JSON stringification
+ */
+function sortObjectKeys(obj) {
+    if (obj === null || typeof obj !== 'object') {
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map(sortObjectKeys);
+    }
+    const sorted = {};
+    const keys = Object.keys(obj).sort();
+    for (const key of keys) {
+        sorted[key] = sortObjectKeys(obj[key]);
+    }
+    return sorted;
+}

package/dist/cache/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Cache module exports
+ */
+export type { CacheProvider, CacheEntry, CacheSetOptions, CacheStats, GateCacheKeyInput, CachedGateResult, } from './types.js';
+export { FileCacheProvider, type FileCacheConfig } from './providers/file-cache.js';
+export { MemoryCacheProvider, type MemoryCacheConfig } from './providers/memory-cache.js';
+export { NullCacheProvider } from './providers/null-cache.js';
+export { generateCacheKey, hashCheckConfig, hashGateConfig, generateInputHash, parseCacheKey, checkInvalidationPattern, allGateInvalidationPattern, } from './cache-key.js';
+import type { CacheProvider } from './types.js';
+export type CacheProviderType = 'file' | 'memory' | 'null';
+export interface CreateCacheOptions {
+    /** Provider type */
+    type: CacheProviderType;
+    /** Workspace root (required for file cache) */
+    workspaceRoot?: string;
+    /** Whether to disable caching */
+    disabled?: boolean;
+    /** Use global cache in home directory */
+    useGlobalCache?: boolean;
+    /** Default TTL in milliseconds */
+    defaultTtl?: number;
+}
+/**
+ * Create a cache provider based on options
+ */
+export declare function createCacheProvider(options: CreateCacheOptions): CacheProvider;
+//# sourceMappingURL=index.d.ts.map

package/dist/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,YAAY,EACV,aAAa,EACb,UAAU,EACV,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACpF,OAAO,EAAE,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAC1F,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAG9D,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,gBAAgB,CAAC;AAGxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAKhD,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE3D,MAAM,WAAW,kBAAkB;IACjC,oBAAoB;IACpB,IAAI,EAAE,iBAAiB,CAAC;IACxB,+CAA+C;IAC/C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iCAAiC;IACjC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,yCAAyC;IACzC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,kBAAkB,GAAG,aAAa,CA0B9E"}

package/dist/cache/index.js

@@ -0,0 +1,38 @@
+/**
+ * Cache module exports
+ */
+// Providers
+export { FileCacheProvider } from './providers/file-cache.js';
+export { MemoryCacheProvider } from './providers/memory-cache.js';
+export { NullCacheProvider } from './providers/null-cache.js';
+// Cache key utilities
+export { generateCacheKey, hashCheckConfig, hashGateConfig, generateInputHash, parseCacheKey, checkInvalidationPattern, allGateInvalidationPattern, } from './cache-key.js';
+import { FileCacheProvider } from './providers/file-cache.js';
+import { MemoryCacheProvider } from './providers/memory-cache.js';
+import { NullCacheProvider } from './providers/null-cache.js';
+/**
+ * Create a cache provider based on options
+ */
+export function createCacheProvider(options) {
+    if (options.disabled) {
+        return new NullCacheProvider();
+    }
+    switch (options.type) {
+        case 'file':
+            if (!options.workspaceRoot) {
+                throw new Error('workspaceRoot is required for file cache provider');
+            }
+            return new FileCacheProvider(options.workspaceRoot, {
+                useGlobalCache: options.useGlobalCache,
+                defaultTtl: options.defaultTtl,
+            });
+        case 'memory':
+            return new MemoryCacheProvider({
+                defaultTtl: options.defaultTtl,
+            });
+        case 'null':
+            return new NullCacheProvider();
+        default:
+            throw new Error(`Unknown cache provider type: ${options.type}`);
+    }
+}

package/dist/cache/providers/file-cache.d.ts

@@ -0,0 +1,63 @@
+/**
+ * File-based cache provider
+ * Stores cache entries as JSON files in .anvil/cache/
+ */
+import type { CacheProvider, CacheEntry, CacheSetOptions, CacheStats } from '../types.js';
+/**
+ * File-based cache provider configuration
+ */
+export interface FileCacheConfig {
+    /** Base directory for cache (default: .anvil/cache in workspace root) */
+    cacheDir?: string;
+    /** Default TTL in milliseconds (default: 24 hours) */
+    defaultTtl?: number;
+    /** Maximum cache size in bytes (default: 100MB) */
+    maxSizeBytes?: number;
+    /** Whether to use global cache in home directory */
+    useGlobalCache?: boolean;
+}
+/**
+ * File-based cache provider
+ *
+ * Storage structure:
+ * .anvil/cache/
+ * ├── index.json         # Cache registry and stats
+ * └── entries/           # Cache entry files
+ *     └── {key-hash}.json
+ */
+export declare class FileCacheProvider implements CacheProvider {
+    readonly name = "file";
+    private readonly cacheDir;
+    private readonly entriesDir;
+    private readonly indexPath;
+    private readonly defaultTtl;
+    private readonly maxSizeBytes;
+    private readonly hmacKey;
+    private index;
+    private indexDirty;
+    constructor(workspaceRoot: string, config?: FileCacheConfig);
+    /**
+     * Load a persisted HMAC key from the cache dir, or generate and store one.
+     * The key is stored with 0o600 permissions so only the current user can read it.
+     */
+    private loadOrCreateHmacKey;
+    get<T>(key: string): Promise<CacheEntry<T> | null>;
+    set<T>(key: string, value: T, options: CacheSetOptions): Promise<void>;
+    invalidate(key: string): Promise<boolean>;
+    invalidatePattern(pattern: string): Promise<number>;
+    getStats(): Promise<CacheStats>;
+    clear(): Promise<void>;
+    isAvailable(): Promise<boolean>;
+    /**
+     * Clean up expired entries
+     */
+    cleanup(): Promise<number>;
+    private ensureCacheDir;
+    private loadIndex;
+    private saveIndex;
+    private computeHmac;
+    private hashKey;
+    private patternToRegex;
+    private maybeEvict;
+}
+//# sourceMappingURL=file-cache.d.ts.map

package/dist/cache/providers/file-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-cache.d.ts","sourceRoot":"","sources":["../../../src/cache/providers/file-cache.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA4D1F;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IACrD,QAAQ,CAAC,IAAI,UAAU;IAEvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,UAAU,CAAS;gBAEf,aAAa,EAAE,MAAM,EAAE,MAAM,GAAE,eAAoB;IAe/D;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAYrB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IA8ElD,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IA0CtE,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA0BzC,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAenD,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC;IAiB/B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAUtB,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAUrC;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;YAiBlB,cAAc;YAMd,SAAS;YAgCT,SAAS;IAWvB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,OAAO;IAKf,OAAO,CAAC,cAAc;YAsBR,UAAU;CA0BzB"}