@vibesdotdev/kit 0.0.0-stage → 1.0.0-rc.4

package/dist/lib/server/locals.js

@@ -0,0 +1,118 @@
+/**
+ * VibesKit Locals Contract
+ *
+ * This module owns the canonical shape of `App.Locals` fields that vibeskit
+ * populates during its handle chain. Consuming apps MUST merge this interface
+ * into their `App.Locals` declaration so that TypeScript accepts the fields
+ * vibeskit writes and reads.
+ *
+ * In your app's `src/app.d.ts`:
+ *
+ * ```ts
+ * import type { VibesKitLocals } from '../index.ts/server';
+ * declare global {
+ *   namespace App {
+ *     interface Locals extends VibesKitLocals {}
+ *   }
+ * }
+ * export {};
+ * ```
+ *
+ * Internally, vibeskit modules access `event.locals` through this contract via
+ * `const locals = event.locals as VibesKitLocals` at module function boundaries.
+ * This ensures fresh-checkout compilation (where App.Locals is not yet merged)
+ * still type-checks cleanly.
+ */
+import { CapabilityError } from '@vibesdotdev/kernel';
+import { bindKitLogger } from './runtime-bound-logger';
+/** Thrown when a kit seam needs the host runtime and `locals.runtime` is absent. */
+export class KitRuntimeUnavailableError extends CapabilityError {
+    constructor() {
+        super('runtime-unavailable: event.locals.runtime was not prepared by the host', 'UNAVAILABLE', {
+            reason: 'runtime-unavailable'
+        });
+        this.name = 'KitRuntimeUnavailableError';
+    }
+}
+/**
+ * Return the request's runtime port or throw a typed `runtime-unavailable`
+ * error. There is no ambient fallback: the host must hand the runtime through
+ * `event.locals.runtime`.
+ */
+export function requireKitRuntime(locals) {
+    if (!locals.runtime) {
+        throw new KitRuntimeUnavailableError();
+    }
+    bindKitLogger(locals.runtime);
+    return locals.runtime;
+}
+/**
+ * Cast `event.locals` to `VibesKitLocals` at a module function boundary.
+ *
+ * Use this helper at the top of handle/middleware/hook function bodies so all
+ * downstream locals accesses are typed without per-line casts.
+ *
+ * This is a zero-runtime-cost structural assertion — `event.locals` IS the
+ * same object; we are only narrowing the type seen by TypeScript.
+ *
+ * @example
+ * ```ts
+ * import { asVibesKitLocals } from '../index.ts/server/locals';
+ *
+ * async function myHandle({ event, resolve }) {
+ *   const locals = asVibesKitLocals(event.locals);
+ *   locals.requestId = generateId();
+ *   return resolve(event);
+ * }
+ * ```
+ */
+export function asVibesKitLocals(locals) {
+    // SAFETY: `App.Locals` is declared by the consuming app, which must merge
+    // `VibesKitLocals` into it (see the module doc); kit cannot name that shape,
+    // so this is the one narrowing at the SvelteKit boundary. The result is the
+    // same object; only the type view of it changes.
+    return locals;
+}
+/**
+ * Resolve the caller's membership role in the active organization.
+ *
+ * Lives here rather than in an org app because nothing about it is
+ * org-specific: it is the generic "prefer the signed claim, fall back to the
+ * account context" rule that any consumer app enforcing org roles needs.
+ * Casework carried its own copy, which is both a doctrine violation (org apps
+ * hold preferences, not logic) and how the two ended up able to disagree.
+ *
+ * ORDER IS THE POINT. The VERIFIED JWT claim is consulted first: it is signed
+ * and needs no subrequest, so a degraded account-web cannot silently demote an
+ * admin. Reading the context alone made every WRITE only as available as
+ * account-web — a failed hop returned null, null is not a writer role, and the
+ * caller was told "you do not have permission", an authorization verdict stated
+ * on the strength of a network error.
+ *
+ * Structural inputs on purpose: vibeskit does not depend on `@vibesdotdev/auth`
+ * or on the account context types. Auth is a producer that writes into locals,
+ * not a dependency of the kit.
+ */
+export function resolveActiveOrgRole(input) {
+    const activeOrgId = input.activeOrgId ?? null;
+    const claims = input.orgs ?? [];
+    if (claims.length > 0) {
+        const claimed = activeOrgId ? claims.find((org) => org.id === activeOrgId) : undefined;
+        // No active org pinned (superuser admin-bypass) falls back to the first
+        // membership, which is what the caller's single-org case always means.
+        const role = (claimed ?? claims[0])?.role;
+        if (role)
+            return role;
+    }
+    // Tokens minted before the claim existed carry `orgs: []`, so an empty claim
+    // is "unknown", not "no memberships" — the context still has to be asked.
+    const organizations = input.contextOrganizations ?? null;
+    if (!organizations)
+        return null;
+    if (activeOrgId) {
+        const match = organizations.find((org) => org.id === activeOrgId || org.membership?.organizationId === activeOrgId);
+        if (match?.membership?.role)
+            return match.membership.role;
+    }
+    return organizations[0]?.membership?.role ?? null;
+}

package/dist/lib/server/middleware/cache-manager.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Cache management middleware for vibeskit
+ *
+ * Uses the injected CacheManager for consistent caching
+ * with automatic invalidation and performance optimization.
+ */
+import { type CachingConfig } from '../../types';
+import type { VibesKitConfig } from '../../types/kit';
+import type { RequestEvent } from '@sveltejs/kit';
+import type { JsonValue } from './json-value.js';
+/**
+ * The key a config without its own key generator gets: method, path, query,
+ * and the user / project when the config is user- or project-based. Request
+ * headers never enter it.
+ */
+export declare function defaultCacheKey(event: RequestEvent, config: CachingConfig): string;
+/**
+ * Cache middleware for vibeskit endpoints
+ */
+export declare class VibesCacheManager {
+    #private;
+    private readonly services?;
+    /**
+     * @param services The injected services to cache and log through. Omitted,
+     * they are read from the initialized kit config at each call.
+     */
+    constructor(services?: VibesKitConfig['services']);
+    /**
+     * Get cached response if available
+     */
+    get<T>(event: RequestEvent, config: CachingConfig): Promise<{
+        hit: boolean;
+        data?: T;
+        key: string;
+    }>;
+    /**
+     * Store response in cache
+     */
+    set<TData>(key: string, data: TData, config: CachingConfig, event: RequestEvent): Promise<boolean>;
+    /**
+     * Invalidate cache entries
+     */
+    invalidate(options: {
+        keys?: string[];
+        pattern?: string;
+        userId?: string;
+        projectId?: string;
+        tags?: string[];
+    }): Promise<void>;
+    /**
+     * Generate cache key from request and config
+     */
+    private generateCacheKey;
+    /**
+     * Invalidate cache entries for a specific user
+     */
+    invalidateUser(userId: string): Promise<void>;
+    /**
+     * Invalidate cache entries for a specific project
+     */
+    invalidateProject(projectId: string): Promise<void>;
+}
+/**
+ * A cache manager for one caller. The cache and logger it uses are the injected
+ * services on the kit config, so no process-wide manager instance carries state
+ * between requests or apps.
+ */
+export declare function createCacheManager(): VibesCacheManager;
+/** What one invalidation call asks for. */
+export type CacheInvalidation = Parameters<VibesCacheManager['invalidate']>[0];
+/**
+ * Apply caching middleware - check for cached response
+ */
+export declare function applyCacheGet<T>(event: RequestEvent, config: CachingConfig): Promise<{
+    hit: boolean;
+    data?: T;
+    key: string;
+}>;
+/**
+ * Apply caching middleware - store response
+ */
+export declare function applyCacheSet<TData>(key: string, data: TData, config: CachingConfig, event: RequestEvent): Promise<boolean>;
+/**
+ * Invalidate cache entries through a manager built for this call.
+ */
+export declare function invalidateCache(options: CacheInvalidation): Promise<void>;
+/**
+ * Cache invalidation utilities
+ */
+export declare const cacheUtils: {
+    /**
+     * Invalidate user-specific caches
+     */
+    invalidateUser(userId: string): Promise<void>;
+    /**
+     * Invalidate project-specific caches
+     */
+    invalidateProject(projectId: string): Promise<void>;
+    /**
+     * Invalidate by pattern
+     */
+    invalidatePattern(pattern: string): Promise<void>;
+    /**
+     * Invalidate specific keys
+     */
+    invalidateKeys(keys: string[]): Promise<void>;
+    /**
+     * Invalidate by tags
+     */
+    invalidateTags(tags: string[]): Promise<void>;
+};
+/**
+ * Cache warming utilities for preloading frequently accessed data
+ */
+export declare const cacheWarming: {
+    /**
+     * Warm cache with data
+     */
+    warmCache<T>(key: string, fetcher: () => Promise<T>, ttl?: number): Promise<void>;
+    /**
+     * Warm multiple cache entries
+     */
+    warmMultiple(entries: Array<{
+        key: string;
+        fetcher: () => Promise<JsonValue>;
+        ttl?: number;
+    }>): Promise<void>;
+};
+/**
+ * Cache middleware wrapper for consistent application
+ */
+export declare const cacheMiddleware: {
+    get: typeof applyCacheGet;
+    set: typeof applyCacheSet;
+    invalidate: (options: CacheInvalidation) => Promise<void>;
+};

package/dist/lib/server/middleware/cache-manager.js

@@ -0,0 +1,327 @@
+/**
+ * Cache management middleware for vibeskit
+ *
+ * Uses the injected CacheManager for consistent caching
+ * with automatic invalidation and performance optimization.
+ */
+import { getVibesKit } from '../../instance';
+import { CacheTTLPresets } from '../../types';
+import * as z from 'zod/v4';
+import { asVibesKitLocals } from '../locals.js';
+import { settle } from '../../attempt.js';
+/** The failure of a refused outcome as the `Error` the injected logger takes. */
+function failureOf(outcome) {
+    return outcome.error instanceof Error ? outcome.error : new Error(String(outcome.error));
+}
+/**
+ * Request-derived text (method, path, query) as key characters, injectively:
+ * every character outside [a-zA-Z0-9-] (including `_` and the `:` delimiter)
+ * becomes `_<hex>_`, so two different requests never share a key and request
+ * text cannot imitate the `user:` / `project:` parts. User and project ids stay
+ * literal, so pattern invalidation (`*user:<id>*`) keeps matching.
+ */
+function escapeKeyPart(text) {
+    return text.replace(/[^a-zA-Z0-9-]/g, (char) => `_${char.codePointAt(0)?.toString(16)}_`);
+}
+/**
+ * The route params a cache key reads: text values only. A param the router
+ * filled with a non-string carries no cache-key fact, so it parses away rather
+ * than reaching the key as `[object Object]`.
+ */
+const CacheKeyParamsSchema = z
+    .record(z.string(), z.unknown())
+    .transform((params) => Object.fromEntries(Object.entries(params).filter((entry) => typeof entry[1] === 'string')));
+/**
+ * The key a config without its own key generator gets: method, path, query,
+ * and the user / project when the config is user- or project-based. Request
+ * headers never enter it.
+ */
+export function defaultCacheKey(event, config) {
+    // Build key from request properties
+    const parts = [];
+    // Add method and path
+    parts.push(escapeKeyPart(event.request.method));
+    parts.push(escapeKeyPart(event.url.pathname));
+    // Add query parameters
+    if (event.url.search) {
+        parts.push(escapeKeyPart(event.url.search));
+    }
+    // Add user ID if user-based caching
+    const locals = asVibesKitLocals(event.locals);
+    if (config.userBased && locals.user?.id) {
+        parts.push(`user:${locals.user.id}`);
+    }
+    // Add project ID if project-based caching
+    if (config.projectBased) {
+        const params = CacheKeyParamsSchema.parse(event.params);
+        const projectId = locals.activeProjectId ||
+            params.projectId ||
+            (event.url.pathname.includes('/projects/') ? params.id : undefined);
+        if (projectId) {
+            parts.push(`project:${projectId}`);
+        }
+    }
+    // Add prefix if specified
+    const prefix = config.prefix || 'vibes';
+    return `${prefix}:${parts.join(':')}`.replace(/[^a-zA-Z0-9:_-]/g, '_');
+}
+/**
+ * A usable time-to-live: finite and positive. Absent means the default;
+ * zero, negative or non-finite means "do not cache", never the default.
+ */
+function storableTtl(ttl) {
+    if (ttl === undefined)
+        return CacheTTLPresets.MEDIUM;
+    return Number.isFinite(ttl) && ttl > 0 ? ttl : null;
+}
+/**
+ * Cache middleware for vibeskit endpoints
+ */
+export class VibesCacheManager {
+    services;
+    /**
+     * @param services The injected services to cache and log through. Omitted,
+     * they are read from the initialized kit config at each call.
+     */
+    constructor(services) {
+        this.services = services;
+    }
+    /** The services this manager caches and logs through. */
+    #services() {
+        return this.services ?? getVibesKit().config.services;
+    }
+    /**
+     * Get cached response if available
+     */
+    async get(event, config) {
+        if (!config.enabled) {
+            return { hit: false, key: '' };
+        }
+        const services = this.#services();
+        const cache = services?.cache;
+        const logger = services?.logger;
+        if (!cache) {
+            logger?.warn('Cache service not injected in vibeskit config');
+            return { hit: false, key: '' };
+        }
+        const key = this.generateCacheKey(event, config);
+        const lookup = await settle(() => cache.get(key));
+        if (!lookup.ok) {
+            logger?.error('Cache get error', failureOf(lookup), {
+                key,
+                path: event.url.pathname,
+                category: 'caching'
+            });
+            return { hit: false, key };
+        }
+        const cached = lookup.value;
+        if (cached !== null) {
+            logger?.debug('Cache hit', {
+                key,
+                path: event.url.pathname,
+                category: 'caching'
+            });
+            return { hit: true, data: cached, key };
+        }
+        logger?.debug('Cache miss', {
+            key,
+            path: event.url.pathname,
+            category: 'caching'
+        });
+        return { hit: false, key };
+    }
+    /**
+     * Store response in cache
+     */
+    async set(key, data, config, event) {
+        if (!config.enabled) {
+            return false;
+        }
+        const services = this.#services();
+        const cache = services?.cache;
+        const logger = services?.logger;
+        if (!cache) {
+            return false;
+        }
+        const ttl = storableTtl(config.ttl);
+        if (ttl === null)
+            return false;
+        const stored = await settle(() => cache.set(key, data, ttl));
+        if (!stored.ok) {
+            logger?.error('Cache set error', failureOf(stored), {
+                key,
+                path: event.url.pathname,
+                category: 'caching'
+            });
+            return false;
+        }
+        if (stored.value) {
+            logger?.debug('Cache set', {
+                key,
+                ttl,
+                path: event.url.pathname,
+                category: 'caching'
+            });
+        }
+        return stored.value;
+    }
+    /**
+     * Invalidate cache entries
+     */
+    async invalidate(options) {
+        const services = this.#services();
+        const cache = services?.cache;
+        const logger = services?.logger;
+        if (!cache)
+            return;
+        const invalidated = await settle(async () => {
+            if (options.keys) {
+                for (const key of options.keys) {
+                    await cache.del(key);
+                }
+            }
+            if (options.pattern) {
+                await cache.flushPattern(options.pattern);
+            }
+            if (options.userId && cache.invalidateUser) {
+                await cache.invalidateUser(options.userId);
+            }
+            if (options.projectId && cache.invalidateProject) {
+                await cache.invalidateProject(options.projectId);
+            }
+            if (options.tags) {
+                // Tag-based invalidation would need to be implemented
+                // For now, we'll use patterns
+                for (const tag of options.tags) {
+                    await cache.flushPattern(`*${tag}*`);
+                }
+            }
+        });
+        if (!invalidated.ok) {
+            logger?.error('Cache invalidation error', failureOf(invalidated), {
+                options,
+                category: 'caching'
+            });
+            return;
+        }
+        logger?.debug('Cache invalidation completed', {
+            options,
+            category: 'caching'
+        });
+    }
+    /**
+     * Generate cache key from request and config
+     */
+    generateCacheKey(event, config) {
+        // Use custom key generator if provided
+        if (config.key) {
+            return config.key(event);
+        }
+        return defaultCacheKey(event, config);
+    }
+    /**
+     * Invalidate cache entries for a specific user
+     */
+    async invalidateUser(userId) {
+        await this.invalidate({ userId });
+    }
+    /**
+     * Invalidate cache entries for a specific project
+     */
+    async invalidateProject(projectId) {
+        await this.invalidate({ projectId });
+    }
+}
+/**
+ * A cache manager for one caller. The cache and logger it uses are the injected
+ * services on the kit config, so no process-wide manager instance carries state
+ * between requests or apps.
+ */
+export function createCacheManager() {
+    return new VibesCacheManager();
+}
+/**
+ * Apply caching middleware - check for cached response
+ */
+export function applyCacheGet(event, config) {
+    return createCacheManager().get(event, config);
+}
+/**
+ * Apply caching middleware - store response
+ */
+export function applyCacheSet(key, data, config, event) {
+    return createCacheManager().set(key, data, config, event);
+}
+/**
+ * Invalidate cache entries through a manager built for this call.
+ */
+export function invalidateCache(options) {
+    return createCacheManager().invalidate(options);
+}
+/**
+ * Cache invalidation utilities
+ */
+export const cacheUtils = {
+    /**
+     * Invalidate user-specific caches
+     */
+    invalidateUser(userId) {
+        return invalidateCache({ userId });
+    },
+    /**
+     * Invalidate project-specific caches
+     */
+    invalidateProject(projectId) {
+        return invalidateCache({ projectId });
+    },
+    /**
+     * Invalidate by pattern
+     */
+    invalidatePattern(pattern) {
+        return invalidateCache({ pattern });
+    },
+    /**
+     * Invalidate specific keys
+     */
+    invalidateKeys(keys) {
+        return invalidateCache({ keys });
+    },
+    /**
+     * Invalidate by tags
+     */
+    invalidateTags(tags) {
+        return invalidateCache({ tags });
+    }
+};
+/**
+ * Cache warming utilities for preloading frequently accessed data
+ */
+export const cacheWarming = {
+    /**
+     * Warm cache with data
+     */
+    async warmCache(key, fetcher, ttl) {
+        const cache = getVibesKit().config.services?.cache;
+        if (!cache)
+            return;
+        const storable = storableTtl(ttl);
+        if (storable === null)
+            return;
+        const data = await fetcher();
+        await cache.set(key, data, storable);
+    },
+    /**
+     * Warm multiple cache entries
+     */
+    async warmMultiple(entries) {
+        await Promise.all(entries.map((entry) => this.warmCache(entry.key, entry.fetcher, entry.ttl)));
+    }
+};
+/**
+ * Cache middleware wrapper for consistent application
+ */
+export const cacheMiddleware = {
+    get: applyCacheGet,
+    set: applyCacheSet,
+    invalidate: (options) => invalidateCache(options)
+};

package/dist/lib/server/middleware/json-value.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A value that survives JSON serialization: what crosses the wire or is
+ * stored in a cache. Named so payload and detail types state their contract
+ * instead of leaving the value open.
+ */
+export type JsonValue = string | number | boolean | null | JsonValue[] | JsonRecord;
+/** A JSON object. */
+export interface JsonRecord {
+    [key: string]: JsonValue;
+}

package/dist/lib/server/middleware/json-value.js

@@ -0,0 +1 @@
+export {};