@timber-js/app 0.1.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IACrE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvF,UAAU,CAAC,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjE;AAGD,MAAM,WAAW,YAAY,CAAC,EAAE,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG;IAC9D,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC;IAC1C,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC;CAC3D;AAED,MAAM,WAAW,yBAAyB;IACxC,2FAA2F;IAC3F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,kBAAmB,YAAW,YAAY;IACrD,OAAO,CAAC,KAAK,CAA4E;IACzF,OAAO,CAAC,OAAO,CAAS;gBAEZ,IAAI,CAAC,EAAE,yBAAyB;IAItC,GAAG,CAAC,GAAG,EAAE,MAAM;;;;IAYf,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE;IAuBtE,UAAU,CAAC,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE;IAarD,gDAAgD;IAChD,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACpE,YAAY,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/cache/index.js

@@ -0,0 +1,283 @@
+import { t as addSpanEvent } from "../_chunks/tracing-BtOwb8O6.js";
+import { createHash } from "node:crypto";
+//#region src/cache/redis-handler.ts
+var KEY_PREFIX = "timber:cache:";
+var TAG_PREFIX = "timber:tag:";
+/**
+* Redis-backed CacheHandler for distributed caching.
+*
+* All instances sharing the same Redis see each other's cache entries and
+* invalidations. Tag-based invalidation uses Redis Sets to track which keys
+* belong to which tags.
+*
+* Bring your own Redis client — any client implementing the RedisClient
+* interface works (ioredis, node-redis, @upstash/redis, etc.).
+*/
+var RedisCacheHandler = class {
+	client;
+	prefix;
+	constructor(client, opts) {
+		this.client = client;
+		this.prefix = opts?.prefix ?? "";
+	}
+	cacheKey(key) {
+		return `${this.prefix}${KEY_PREFIX}${key}`;
+	}
+	tagKey(tag) {
+		return `${this.prefix}${TAG_PREFIX}${tag}`;
+	}
+	async get(key) {
+		const raw = await this.client.get(this.cacheKey(key));
+		if (raw === null) return null;
+		const entry = JSON.parse(raw);
+		const stale = Date.now() > entry.expiresAt;
+		return {
+			value: entry.value,
+			stale
+		};
+	}
+	async set(key, value, opts) {
+		const ck = this.cacheKey(key);
+		const expiresAt = Date.now() + opts.ttl * 1e3;
+		const payload = JSON.stringify({
+			value,
+			expiresAt
+		});
+		const redisTtlSeconds = Math.max(opts.ttl * 2 + 60, 120);
+		await this.client.set(ck, payload, "EX", redisTtlSeconds);
+		for (const tag of opts.tags) await this.client.sadd(this.tagKey(tag), key);
+	}
+	async invalidate(opts) {
+		if (opts.key) await this.client.del(this.cacheKey(opts.key));
+		if (opts.tag) {
+			const tk = this.tagKey(opts.tag);
+			const keys = await this.client.smembers(tk);
+			if (keys.length > 0) {
+				const cacheKeys = keys.map((k) => this.cacheKey(k));
+				await this.client.del(cacheKeys);
+			}
+			await this.client.del(tk);
+		}
+	}
+};
+//#endregion
+//#region src/cache/stable-stringify.ts
+/**
+* Deterministic JSON serialization with sorted object keys.
+* Used for cache key generation — ensures { a: 1, b: 2 } and { b: 2, a: 1 }
+* produce the same string.
+*/
+function stableStringify(value) {
+	if (value === null || value === void 0) return JSON.stringify(value);
+	if (typeof value !== "object") return JSON.stringify(value);
+	if (Array.isArray(value)) return "[" + value.map((item) => stableStringify(item)).join(",") + "]";
+	const obj = value;
+	const keys = Object.keys(obj).sort();
+	const pairs = [];
+	for (const key of keys) {
+		if (obj[key] === void 0) continue;
+		pairs.push(JSON.stringify(key) + ":" + stableStringify(obj[key]));
+	}
+	return "{" + pairs.join(",") + "}";
+}
+//#endregion
+//#region src/cache/singleflight.ts
+function createSingleflight() {
+	const inflight = /* @__PURE__ */ new Map();
+	return { do(key, fn) {
+		const existing = inflight.get(key);
+		if (existing) return existing;
+		const promise = fn().finally(() => {
+			inflight.delete(key);
+		});
+		inflight.set(key, promise);
+		return promise;
+	} };
+}
+//#endregion
+//#region src/cache/timber-cache.ts
+var singleflight$1 = createSingleflight();
+/**
+* Generate a SHA-256 cache key from function identity and serialized args.
+*/
+function defaultKeyGenerator(fnId, args) {
+	const raw = fnId + ":" + stableStringify(args);
+	return createHash("sha256").update(raw).digest("hex");
+}
+/**
+* Resolve tags from the options — supports static array or function form.
+*/
+function resolveTags$1(opts, args) {
+	if (!opts.tags) return [];
+	if (Array.isArray(opts.tags)) return opts.tags;
+	return opts.tags(...args);
+}
+var fnIdCounter = 0;
+/**
+* Creates a cached wrapper around an async function.
+*
+* - SHA-256 default keys with normalized JSON args
+* - Singleflight: concurrent misses → single execution
+* - SWR: serve stale immediately, background refetch
+* - Tags as string[] or function of args
+* - No ALS dependency
+*
+* Cache hits/misses are recorded as OTEL span events on the enclosing
+* span (not child spans). The DevSpanProcessor reads these for dev log output.
+*/
+function createCache(fn, opts, handler) {
+	const fnId = `timber-cache:${fnIdCounter++}`;
+	return async (...args) => {
+		const key = opts.key ? opts.key(...args) : defaultKeyGenerator(fnId, args);
+		const cacheStart = performance.now();
+		const cached = await handler.get(key);
+		if (cached && !cached.stale) {
+			await addSpanEvent("timber.cache.hit", {
+				key,
+				duration_ms: Math.round(performance.now() - cacheStart)
+			});
+			return cached.value;
+		}
+		if (cached && cached.stale && opts.staleWhileRevalidate) {
+			await addSpanEvent("timber.cache.hit", {
+				key,
+				duration_ms: Math.round(performance.now() - cacheStart),
+				stale: true
+			});
+			singleflight$1.do(`swr:${key}`, async () => {
+				try {
+					const fresh = await fn(...args);
+					const tags = resolveTags$1(opts, args);
+					await handler.set(key, fresh, {
+						ttl: opts.ttl,
+						tags
+					});
+				} catch {}
+			}).catch(() => {});
+			return cached.value;
+		}
+		const result = await singleflight$1.do(key, () => fn(...args));
+		const tags = resolveTags$1(opts, args);
+		await handler.set(key, result, {
+			ttl: opts.ttl,
+			tags
+		});
+		await addSpanEvent("timber.cache.miss", {
+			key,
+			duration_ms: Math.round(performance.now() - cacheStart)
+		});
+		return result;
+	};
+}
+/**
+* Invalidate cache entries by tag or key.
+*/
+createCache.invalidate = async function invalidate(handler, opts) {
+	await handler.invalidate(opts);
+};
+//#endregion
+//#region src/cache/register-cached-function.ts
+var singleflight = createSingleflight();
+var REQUEST_SPECIFIC_PROPS = new Set([
+	"cookies",
+	"cookie",
+	"session",
+	"sessionId",
+	"token",
+	"authorization",
+	"auth",
+	"headers"
+]);
+/**
+* Generate a SHA-256 cache key from a stable function ID and serialized args.
+*/
+function generateKey(id, args) {
+	const raw = id + ":" + stableStringify(args);
+	return createHash("sha256").update(raw).digest("hex");
+}
+/**
+* Resolve tags from options — supports static array or function form.
+*/
+function resolveTags(opts, args) {
+	if (!opts.tags) return [];
+	if (Array.isArray(opts.tags)) return opts.tags;
+	return opts.tags(...args);
+}
+/**
+* Checks if component props contain request-specific keys and emits a dev warning.
+* Only runs when process.env.NODE_ENV !== 'production'.
+*/
+function warnRequestSpecificProps(id, props) {
+	if (typeof props !== "object" || props === null) return;
+	const suspicious = Object.keys(props).filter((k) => REQUEST_SPECIFIC_PROPS.has(k.toLowerCase()));
+	if (suspicious.length > 0) console.warn(`[timber] "use cache" component ${id} received request-specific props: ${suspicious.join(", ")}. This may serve one user's cached render to another user. Remove request-specific data from props or remove "use cache".`);
+}
+/**
+* Runtime for the "use cache" directive transform. Wraps an async function
+* with caching using the same cache handler as timber.cache.
+*
+* The stable `id` (file path + function name) ensures cache keys are consistent
+* across builds. Args/props are hashed with SHA-256 for the per-call key.
+*/
+function registerCachedFunction(fn, opts, handler) {
+	return async (...args) => {
+		if (opts.isComponent && process.env.NODE_ENV !== "production" && args.length > 0) warnRequestSpecificProps(opts.id, args[0]);
+		const key = generateKey(opts.id, args);
+		const cached = await handler.get(key);
+		if (cached && !cached.stale) return cached.value;
+		const result = await singleflight.do(key, () => fn(...args));
+		const tags = resolveTags(opts, args);
+		await handler.set(key, result, {
+			ttl: opts.ttl,
+			tags
+		});
+		return result;
+	};
+}
+//#endregion
+//#region src/cache/index.ts
+var MemoryCacheHandler = class {
+	store = /* @__PURE__ */ new Map();
+	maxSize;
+	constructor(opts) {
+		this.maxSize = opts?.maxSize ?? 1e3;
+	}
+	async get(key) {
+		const entry = this.store.get(key);
+		if (!entry) return null;
+		this.store.delete(key);
+		this.store.set(key, entry);
+		const stale = Date.now() > entry.expiresAt;
+		return {
+			value: entry.value,
+			stale
+		};
+	}
+	async set(key, value, opts) {
+		if (this.store.has(key)) this.store.delete(key);
+		while (this.store.size >= this.maxSize) {
+			const oldest = this.store.keys().next().value;
+			if (oldest !== void 0) this.store.delete(oldest);
+			else break;
+		}
+		this.store.set(key, {
+			value,
+			expiresAt: Date.now() + opts.ttl * 1e3,
+			tags: opts.tags
+		});
+	}
+	async invalidate(opts) {
+		if (opts.key) this.store.delete(opts.key);
+		if (opts.tag) {
+			for (const [key, entry] of this.store) if (entry.tags.includes(opts.tag)) this.store.delete(key);
+		}
+	}
+	/** Number of entries currently in the cache. */
+	get size() {
+		return this.store.size;
+	}
+};
+//#endregion
+export { MemoryCacheHandler, RedisCacheHandler, createCache, createSingleflight, registerCachedFunction, stableStringify };
+
+//# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/cache/redis-handler.ts","../../src/cache/stable-stringify.ts","../../src/cache/singleflight.ts","../../src/cache/timber-cache.ts","../../src/cache/register-cached-function.ts","../../src/cache/index.ts"],"sourcesContent":["import type { CacheHandler } from './index';\n\n/**\n * Minimal Redis client interface — compatible with ioredis, node-redis, and\n * Cloudflare Workers Redis bindings. We depend on the interface, not the\n * implementation, so users bring their own Redis client.\n */\nexport interface RedisClient {\n  get(key: string): Promise<string | null>;\n  set(key: string, value: string, ...args: unknown[]): Promise<unknown>;\n  del(key: string | string[]): Promise<number>;\n  sadd(key: string, ...members: string[]): Promise<number>;\n  smembers(key: string): Promise<string[]>;\n}\n\nconst KEY_PREFIX = 'timber:cache:';\nconst TAG_PREFIX = 'timber:tag:';\n\n/**\n * Redis-backed CacheHandler for distributed caching.\n *\n * All instances sharing the same Redis see each other's cache entries and\n * invalidations. Tag-based invalidation uses Redis Sets to track which keys\n * belong to which tags.\n *\n * Bring your own Redis client — any client implementing the RedisClient\n * interface works (ioredis, node-redis, @upstash/redis, etc.).\n */\nexport class RedisCacheHandler implements CacheHandler {\n  private client: RedisClient;\n  private prefix: string;\n\n  constructor(client: RedisClient, opts?: { prefix?: string }) {\n    this.client = client;\n    this.prefix = opts?.prefix ?? '';\n  }\n\n  private cacheKey(key: string): string {\n    return `${this.prefix}${KEY_PREFIX}${key}`;\n  }\n\n  private tagKey(tag: string): string {\n    return `${this.prefix}${TAG_PREFIX}${tag}`;\n  }\n\n  async get(key: string): Promise<{ value: unknown; stale: boolean } | null> {\n    const raw = await this.client.get(this.cacheKey(key));\n    if (raw === null) return null;\n\n    const entry = JSON.parse(raw) as { value: unknown; expiresAt: number };\n    const stale = Date.now() > entry.expiresAt;\n    return { value: entry.value, stale };\n  }\n\n  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void> {\n    const ck = this.cacheKey(key);\n    const expiresAt = Date.now() + opts.ttl * 1000;\n    const payload = JSON.stringify({ value, expiresAt });\n\n    // Redis TTL with generous margin beyond the logical TTL to allow SWR reads\n    // on stale entries. The logical staleness is determined by expiresAt.\n    // We use 2x TTL + 60s as the Redis expiry so stale entries remain\n    // available for SWR background refetches.\n    const redisTtlSeconds = Math.max(opts.ttl * 2 + 60, 120);\n    await this.client.set(ck, payload, 'EX', redisTtlSeconds);\n\n    // Track key membership in each tag set\n    for (const tag of opts.tags) {\n      await this.client.sadd(this.tagKey(tag), key);\n    }\n  }\n\n  async invalidate(opts: { key?: string; tag?: string }): Promise<void> {\n    if (opts.key) {\n      await this.client.del(this.cacheKey(opts.key));\n    }\n\n    if (opts.tag) {\n      const tk = this.tagKey(opts.tag);\n      const keys = await this.client.smembers(tk);\n\n      if (keys.length > 0) {\n        const cacheKeys = keys.map((k) => this.cacheKey(k));\n        await this.client.del(cacheKeys);\n      }\n\n      // Clean up the tag set itself\n      await this.client.del(tk);\n    }\n  }\n}\n","/**\n * Deterministic JSON serialization with sorted object keys.\n * Used for cache key generation — ensures { a: 1, b: 2 } and { b: 2, a: 1 }\n * produce the same string.\n */\nexport function stableStringify(value: unknown): string {\n  if (value === null || value === undefined) return JSON.stringify(value);\n  if (typeof value !== 'object') return JSON.stringify(value);\n  if (Array.isArray(value)) {\n    return '[' + value.map((item) => stableStringify(item)).join(',') + ']';\n  }\n\n  const obj = value as Record<string, unknown>;\n  const keys = Object.keys(obj).sort();\n  const pairs: string[] = [];\n  for (const key of keys) {\n    if (obj[key] === undefined) continue;\n    pairs.push(JSON.stringify(key) + ':' + stableStringify(obj[key]));\n  }\n  return '{' + pairs.join(',') + '}';\n}\n","/**\n * Singleflight coalesces concurrent calls with the same key into a single\n * execution. All callers receive the same result (or error).\n *\n * Per-process, in-memory. Each process coalesces independently.\n */\nexport interface Singleflight {\n  do<T>(key: string, fn: () => Promise<T>): Promise<T>;\n}\n\nexport function createSingleflight(): Singleflight {\n  const inflight = new Map<string, Promise<unknown>>();\n\n  return {\n    do<T>(key: string, fn: () => Promise<T>): Promise<T> {\n      const existing = inflight.get(key);\n      if (existing) return existing as Promise<T>;\n\n      const promise = fn().finally(() => {\n        inflight.delete(key);\n      });\n      inflight.set(key, promise);\n      return promise;\n    },\n  };\n}\n","import { createHash } from 'node:crypto';\nimport type { CacheHandler, CacheOptions } from './index';\nimport { stableStringify } from './stable-stringify';\nimport { createSingleflight } from './singleflight';\nimport { addSpanEvent } from '#/server/tracing.js';\n\nconst singleflight = createSingleflight();\n\n/**\n * Generate a SHA-256 cache key from function identity and serialized args.\n */\nfunction defaultKeyGenerator(fnId: string, args: unknown[]): string {\n  const raw = fnId + ':' + stableStringify(args);\n  return createHash('sha256').update(raw).digest('hex');\n}\n\n/**\n * Resolve tags from the options — supports static array or function form.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nfunction resolveTags<Fn extends (...args: any[]) => any>(\n  opts: CacheOptions<Fn>,\n  args: Parameters<Fn>\n): string[] {\n  if (!opts.tags) return [];\n  if (Array.isArray(opts.tags)) return opts.tags;\n  return opts.tags(...args);\n}\n\n// Counter for generating unique function IDs when no explicit key is provided.\nlet fnIdCounter = 0;\n\n/**\n * Creates a cached wrapper around an async function.\n *\n * - SHA-256 default keys with normalized JSON args\n * - Singleflight: concurrent misses → single execution\n * - SWR: serve stale immediately, background refetch\n * - Tags as string[] or function of args\n * - No ALS dependency\n *\n * Cache hits/misses are recorded as OTEL span events on the enclosing\n * span (not child spans). The DevSpanProcessor reads these for dev log output.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function createCache<Fn extends (...args: any[]) => Promise<any>>(\n  fn: Fn,\n  opts: CacheOptions<Fn>,\n  handler: CacheHandler\n): (...args: Parameters<Fn>) => Promise<Awaited<ReturnType<Fn>>> {\n  const fnId = `timber-cache:${fnIdCounter++}`;\n\n  return async (...args: Parameters<Fn>): Promise<Awaited<ReturnType<Fn>>> => {\n    const key = opts.key ? opts.key(...args) : defaultKeyGenerator(fnId, args);\n\n    const cacheStart = performance.now();\n    const cached = await handler.get(key);\n\n    if (cached && !cached.stale) {\n      // Record as OTEL span event on enclosing span (not a child span)\n      await addSpanEvent('timber.cache.hit', {\n        key,\n        duration_ms: Math.round(performance.now() - cacheStart),\n      });\n      return cached.value as Awaited<ReturnType<Fn>>;\n    }\n\n    if (cached && cached.stale && opts.staleWhileRevalidate) {\n      // Record stale cache hit as OTEL span event\n      await addSpanEvent('timber.cache.hit', {\n        key,\n        duration_ms: Math.round(performance.now() - cacheStart),\n        stale: true,\n      });\n      // Serve stale immediately, trigger background refetch\n      singleflight\n        .do(`swr:${key}`, async () => {\n          try {\n            const fresh = await fn(...args);\n            const tags = resolveTags(opts, args);\n            await handler.set(key, fresh, { ttl: opts.ttl, tags });\n          } catch {\n            // Failed refetch — stale entry continues to be served.\n            // Error is swallowed per design doc: \"Error is logged.\"\n          }\n        })\n        .catch(() => {\n          // Singleflight promise rejection handled — stale continues.\n        });\n      return cached.value as Awaited<ReturnType<Fn>>;\n    }\n\n    // Cache miss (or stale without SWR) — execute with singleflight\n    const result = await singleflight.do(key, () => fn(...args));\n    const tags = resolveTags(opts, args);\n    await handler.set(key, result, { ttl: opts.ttl, tags });\n\n    // Record cache miss as OTEL span event\n    await addSpanEvent('timber.cache.miss', {\n      key,\n      duration_ms: Math.round(performance.now() - cacheStart),\n    });\n\n    return result as Awaited<ReturnType<Fn>>;\n  };\n}\n\n/**\n * Invalidate cache entries by tag or key.\n */\ncreateCache.invalidate = async function invalidate(\n  handler: CacheHandler,\n  opts: { key?: string; tag?: string }\n): Promise<void> {\n  await handler.invalidate(opts);\n};\n","import { createHash } from 'node:crypto';\nimport type { CacheHandler } from './index';\nimport { stableStringify } from './stable-stringify';\nimport { createSingleflight } from './singleflight';\n\nconst singleflight = createSingleflight();\n\n// Prop names that suggest request-specific data — triggers dev warning for \"use cache\" components.\nconst REQUEST_SPECIFIC_PROPS = new Set([\n  'cookies',\n  'cookie',\n  'session',\n  'sessionId',\n  'token',\n  'authorization',\n  'auth',\n  'headers',\n]);\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface RegisterCachedFunctionOptions<Fn extends (...args: any[]) => any> {\n  ttl: number;\n  id: string;\n  tags?: string[] | ((...args: Parameters<Fn>) => string[]);\n  /** True when the cached function is a React component (PascalCase name). */\n  isComponent?: boolean;\n}\n\n/**\n * Generate a SHA-256 cache key from a stable function ID and serialized args.\n */\nfunction generateKey(id: string, args: unknown[]): string {\n  const raw = id + ':' + stableStringify(args);\n  return createHash('sha256').update(raw).digest('hex');\n}\n\n/**\n * Resolve tags from options — supports static array or function form.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nfunction resolveTags<Fn extends (...args: any[]) => any>(\n  opts: RegisterCachedFunctionOptions<Fn>,\n  args: Parameters<Fn>\n): string[] {\n  if (!opts.tags) return [];\n  if (Array.isArray(opts.tags)) return opts.tags;\n  return opts.tags(...args);\n}\n\n/**\n * Checks if component props contain request-specific keys and emits a dev warning.\n * Only runs when process.env.NODE_ENV !== 'production'.\n */\nfunction warnRequestSpecificProps(id: string, props: unknown): void {\n  if (typeof props !== 'object' || props === null) return;\n  const keys = Object.keys(props);\n  const suspicious = keys.filter((k) => REQUEST_SPECIFIC_PROPS.has(k.toLowerCase()));\n  if (suspicious.length > 0) {\n    console.warn(\n      `[timber] \"use cache\" component ${id} received request-specific props: ${suspicious.join(', ')}. ` +\n        `This may serve one user's cached render to another user. ` +\n        `Remove request-specific data from props or remove \"use cache\".`\n    );\n  }\n}\n\n/**\n * Runtime for the \"use cache\" directive transform. Wraps an async function\n * with caching using the same cache handler as timber.cache.\n *\n * The stable `id` (file path + function name) ensures cache keys are consistent\n * across builds. Args/props are hashed with SHA-256 for the per-call key.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function registerCachedFunction<Fn extends (...args: any[]) => Promise<any>>(\n  fn: Fn,\n  opts: RegisterCachedFunctionOptions<Fn>,\n  handler: CacheHandler\n): (...args: Parameters<Fn>) => Promise<Awaited<ReturnType<Fn>>> {\n  return async (...args: Parameters<Fn>): Promise<Awaited<ReturnType<Fn>>> => {\n    // Dev-mode warning for components with request-specific props\n    if (opts.isComponent && process.env.NODE_ENV !== 'production' && args.length > 0) {\n      warnRequestSpecificProps(opts.id, args[0]);\n    }\n\n    const key = generateKey(opts.id, args);\n    const cached = await handler.get(key);\n\n    if (cached && !cached.stale) {\n      return cached.value as Awaited<ReturnType<Fn>>;\n    }\n\n    // Cache miss or stale — execute with singleflight\n    const result = await singleflight.do(key, () => fn(...args));\n    const tags = resolveTags(opts, args);\n    await handler.set(key, result, { ttl: opts.ttl, tags });\n    return result as Awaited<ReturnType<Fn>>;\n  };\n}\n","// @timber/app/cache — Caching primitives\n\nexport interface CacheHandler {\n  get(key: string): Promise<{ value: unknown; stale: boolean } | null>;\n  set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void>;\n  invalidate(opts: { key?: string; tag?: string }): Promise<void>;\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface CacheOptions<Fn extends (...args: any[]) => any> {\n  ttl: number;\n  key?: (...args: Parameters<Fn>) => string;\n  staleWhileRevalidate?: boolean;\n  tags?: string[] | ((...args: Parameters<Fn>) => string[]);\n}\n\nexport interface MemoryCacheHandlerOptions {\n  /** Maximum number of entries. Oldest accessed entries are evicted first. Default: 1000. */\n  maxSize?: number;\n}\n\nexport class MemoryCacheHandler implements CacheHandler {\n  private store = new Map<string, { value: unknown; expiresAt: number; tags: string[] }>();\n  private maxSize: number;\n\n  constructor(opts?: MemoryCacheHandlerOptions) {\n    this.maxSize = opts?.maxSize ?? 1000;\n  }\n\n  async get(key: string) {\n    const entry = this.store.get(key);\n    if (!entry) return null;\n\n    // Move to end of Map (most recently used) for LRU ordering\n    this.store.delete(key);\n    this.store.set(key, entry);\n\n    const stale = Date.now() > entry.expiresAt;\n    return { value: entry.value, stale };\n  }\n\n  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }) {\n    // If key already exists, delete first to refresh insertion order\n    if (this.store.has(key)) {\n      this.store.delete(key);\n    }\n\n    // Evict oldest entries (front of Map) if at capacity\n    while (this.store.size >= this.maxSize) {\n      const oldest = this.store.keys().next().value;\n      if (oldest !== undefined) {\n        this.store.delete(oldest);\n      } else {\n        break;\n      }\n    }\n\n    this.store.set(key, {\n      value,\n      expiresAt: Date.now() + opts.ttl * 1000,\n      tags: opts.tags,\n    });\n  }\n\n  async invalidate(opts: { key?: string; tag?: string }) {\n    if (opts.key) {\n      this.store.delete(opts.key);\n    }\n    if (opts.tag) {\n      for (const [key, entry] of this.store) {\n        if (entry.tags.includes(opts.tag)) {\n          this.store.delete(key);\n        }\n      }\n    }\n  }\n\n  /** Number of entries currently in the cache. */\n  get size(): number {\n    return this.store.size;\n  }\n}\n\nexport { RedisCacheHandler } from './redis-handler';\nexport type { RedisClient } from './redis-handler';\nexport { createCache } from './timber-cache';\nexport { registerCachedFunction } from './register-cached-function';\nexport type { RegisterCachedFunctionOptions } from './register-cached-function';\nexport { stableStringify } from './stable-stringify';\nexport { createSingleflight } from './singleflight';\nexport type { Singleflight } from './singleflight';\n"],"mappings":"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"}

package/dist/cache/redis-handler.d.ts

@@ -0,0 +1,45 @@
+import type { CacheHandler } from './index';
+/**
+ * Minimal Redis client interface — compatible with ioredis, node-redis, and
+ * Cloudflare Workers Redis bindings. We depend on the interface, not the
+ * implementation, so users bring their own Redis client.
+ */
+export interface RedisClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ...args: unknown[]): Promise<unknown>;
+    del(key: string | string[]): Promise<number>;
+    sadd(key: string, ...members: string[]): Promise<number>;
+    smembers(key: string): Promise<string[]>;
+}
+/**
+ * Redis-backed CacheHandler for distributed caching.
+ *
+ * All instances sharing the same Redis see each other's cache entries and
+ * invalidations. Tag-based invalidation uses Redis Sets to track which keys
+ * belong to which tags.
+ *
+ * Bring your own Redis client — any client implementing the RedisClient
+ * interface works (ioredis, node-redis, @upstash/redis, etc.).
+ */
+export declare class RedisCacheHandler implements CacheHandler {
+    private client;
+    private prefix;
+    constructor(client: RedisClient, opts?: {
+        prefix?: string;
+    });
+    private cacheKey;
+    private tagKey;
+    get(key: string): Promise<{
+        value: unknown;
+        stale: boolean;
+    } | null>;
+    set(key: string, value: unknown, opts: {
+        ttl: number;
+        tags: string[];
+    }): Promise<void>;
+    invalidate(opts: {
+        key?: string;
+        tag?: string;
+    }): Promise<void>;
+}
+//# sourceMappingURL=redis-handler.d.ts.map

package/dist/cache/redis-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-handler.d.ts","sourceRoot":"","sources":["../../src/cache/redis-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACzD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC1C;AAKD;;;;;;;;;GASG;AACH,qBAAa,iBAAkB,YAAW,YAAY;IACpD,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;IAK3D,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,MAAM;IAIR,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IASpE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBtF,UAAU,CAAC,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAkBtE"}

package/dist/cache/register-cached-function.d.ts

@@ -0,0 +1,17 @@
+import type { CacheHandler } from './index';
+export interface RegisterCachedFunctionOptions<Fn extends (...args: any[]) => any> {
+    ttl: number;
+    id: string;
+    tags?: string[] | ((...args: Parameters<Fn>) => string[]);
+    /** True when the cached function is a React component (PascalCase name). */
+    isComponent?: boolean;
+}
+/**
+ * Runtime for the "use cache" directive transform. Wraps an async function
+ * with caching using the same cache handler as timber.cache.
+ *
+ * The stable `id` (file path + function name) ensures cache keys are consistent
+ * across builds. Args/props are hashed with SHA-256 for the per-call key.
+ */
+export declare function registerCachedFunction<Fn extends (...args: any[]) => Promise<any>>(fn: Fn, opts: RegisterCachedFunctionOptions<Fn>, handler: CacheHandler): (...args: Parameters<Fn>) => Promise<Awaited<ReturnType<Fn>>>;
+//# sourceMappingURL=register-cached-function.d.ts.map

package/dist/cache/register-cached-function.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-cached-function.d.ts","sourceRoot":"","sources":["../../src/cache/register-cached-function.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAmB5C,MAAM,WAAW,6BAA6B,CAAC,EAAE,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG;IAC/E,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC;IAC1D,4EAA4E;IAC5E,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAwCD;;;;;;GAMG;AAEH,wBAAgB,sBAAsB,CAAC,EAAE,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EAChF,EAAE,EAAE,EAAE,EACN,IAAI,EAAE,6BAA6B,CAAC,EAAE,CAAC,EACvC,OAAO,EAAE,YAAY,GACpB,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAoB/D"}

package/dist/cache/singleflight.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Singleflight coalesces concurrent calls with the same key into a single
+ * execution. All callers receive the same result (or error).
+ *
+ * Per-process, in-memory. Each process coalesces independently.
+ */
+export interface Singleflight {
+    do<T>(key: string, fn: () => Promise<T>): Promise<T>;
+}
+export declare function createSingleflight(): Singleflight;
+//# sourceMappingURL=singleflight.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"singleflight.d.ts","sourceRoot":"","sources":["../../src/cache/singleflight.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACtD;AAED,wBAAgB,kBAAkB,IAAI,YAAY,CAejD"}

package/dist/cache/stable-stringify.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Deterministic JSON serialization with sorted object keys.
+ * Used for cache key generation — ensures { a: 1, b: 2 } and { b: 2, a: 1 }
+ * produce the same string.
+ */
+export declare function stableStringify(value: unknown): string;
+//# sourceMappingURL=stable-stringify.d.ts.map

package/dist/cache/stable-stringify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stable-stringify.d.ts","sourceRoot":"","sources":["../../src/cache/stable-stringify.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAetD"}

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

@@ -0,0 +1,21 @@
+import type { CacheHandler, CacheOptions } from './index';
+/**
+ * Creates a cached wrapper around an async function.
+ *
+ * - SHA-256 default keys with normalized JSON args
+ * - Singleflight: concurrent misses → single execution
+ * - SWR: serve stale immediately, background refetch
+ * - Tags as string[] or function of args
+ * - No ALS dependency
+ *
+ * Cache hits/misses are recorded as OTEL span events on the enclosing
+ * span (not child spans). The DevSpanProcessor reads these for dev log output.
+ */
+export declare function createCache<Fn extends (...args: any[]) => Promise<any>>(fn: Fn, opts: CacheOptions<Fn>, handler: CacheHandler): (...args: Parameters<Fn>) => Promise<Awaited<ReturnType<Fn>>>;
+export declare namespace createCache {
+    var invalidate: (handler: CacheHandler, opts: {
+        key?: string;
+        tag?: string;
+    }) => Promise<void>;
+}
+//# sourceMappingURL=timber-cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"timber-cache.d.ts","sourceRoot":"","sources":["../../src/cache/timber-cache.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AA+B1D;;;;;;;;;;;GAWG;AAEH,wBAAgB,WAAW,CAAC,EAAE,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EACrE,EAAE,EAAE,EAAE,EACN,IAAI,EAAE,YAAY,CAAC,EAAE,CAAC,EACtB,OAAO,EAAE,YAAY,GACpB,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAwD/D;yBA5De,WAAW;8BAkEhB,YAAY,QACf;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,KACnC,OAAO,CAAC,IAAI,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+declare const COMMANDS: readonly ["dev", "build", "preview", "check"];
+type Command = (typeof COMMANDS)[number];
+export interface ParsedArgs {
+    command: Command;
+    config: string | undefined;
+}
+export interface CommandOptions {
+    config?: string;
+}
+/**
+ * Parse CLI arguments into a structured command + options.
+ * Accepts: timber <command> [--config|-c <path>]
+ */
+export declare function parseArgs(args: string[]): ParsedArgs;
+/**
+ * Start the Vite dev server.
+ * Middleware re-runs on file change via HMR wiring in timber-routing.
+ */
+export declare function runDev(options: CommandOptions): Promise<void>;
+/**
+ * Run the production build using createBuilder + buildApp.
+ * Direct build() calls do NOT trigger the RSC plugin's multi-environment
+ * pipeline — createBuilder/buildApp is required.
+ */
+export declare function runBuild(options: CommandOptions): Promise<void>;
+/**
+ * Determine whether to use the adapter's preview or Vite's built-in preview.
+ * Exported for testing — the actual runPreview function uses this internally.
+ */
+export declare function resolvePreviewStrategy(adapter: import('./adapters/types').TimberPlatformAdapter | undefined): 'adapter' | 'vite';
+/**
+ * Serve the production build for local testing.
+ * If the adapter provides a preview() method, it takes priority.
+ * Otherwise falls back to Vite's built-in preview server.
+ */
+export declare function runPreview(options: CommandOptions): Promise<void>;
+/**
+ * Validate types and routes without producing build output.
+ * Runs tsgo --noEmit for type checking.
+ */
+export declare function runCheck(options: CommandOptions): Promise<void>;
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAaA,QAAA,MAAM,QAAQ,+CAAgD,CAAC;AAC/D,KAAK,OAAO,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzC,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAuBpD;AAID;;;GAGG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAOnE;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAMrE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,kBAAkB,EAAE,qBAAqB,GAAG,SAAS,GACpE,SAAS,GAAG,MAAM,CAKpB;AA2BD;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBvE;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAerE"}

package/dist/cli.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+//#region src/cli.ts
+var COMMANDS = [
+	"dev",
+	"build",
+	"preview",
+	"check"
+];
+/**
+* Parse CLI arguments into a structured command + options.
+* Accepts: timber <command> [--config|-c <path>]
+*/
+function parseArgs(args) {
+	if (args.length === 0) throw new Error("No command provided. Usage: timber <dev|build|preview|check> [--config <path>]");
+	const command = args[0];
+	if (!COMMANDS.includes(command)) throw new Error(`Unknown command: ${command}. Available commands: ${COMMANDS.join(", ")}`);
+	let config;
+	for (let i = 1; i < args.length; i++) if (args[i] === "--config" || args[i] === "-c") {
+		config = args[++i];
+		if (!config) throw new Error("--config requires a path argument");
+	}
+	return {
+		command,
+		config
+	};
+}
+/**
+* Start the Vite dev server.
+* Middleware re-runs on file change via HMR wiring in timber-routing.
+*/
+async function runDev(options) {
+	const { createServer } = await import("vite");
+	const server = await createServer({ configFile: options.config });
+	await server.listen();
+	server.printUrls();
+}
+/**
+* Run the production build using createBuilder + buildApp.
+* Direct build() calls do NOT trigger the RSC plugin's multi-environment
+* pipeline — createBuilder/buildApp is required.
+*/
+async function runBuild(options) {
+	const { createBuilder } = await import("vite");
+	await (await createBuilder({ configFile: options.config })).buildApp();
+}
+/**
+* Determine whether to use the adapter's preview or Vite's built-in preview.
+* Exported for testing — the actual runPreview function uses this internally.
+*/
+function resolvePreviewStrategy(adapter) {
+	if (adapter && typeof adapter.preview === "function") return "adapter";
+	return "vite";
+}
+/**
+* Load timber.config.ts from the project root.
+* Returns the config object with adapter, output, etc.
+* Returns null if no config file is found.
+*/
+async function loadTimberConfig(root) {
+	const { existsSync } = await import("node:fs");
+	const { join } = await import("node:path");
+	const { pathToFileURL } = await import("node:url");
+	for (const name of [
+		"timber.config.ts",
+		"timber.config.js",
+		"timber.config.mjs"
+	]) {
+		const configPath = join(root, name);
+		if (existsSync(configPath)) {
+			const mod = await import(pathToFileURL(configPath).href);
+			return mod.default ?? mod;
+		}
+	}
+	return null;
+}
+/**
+* Serve the production build for local testing.
+* If the adapter provides a preview() method, it takes priority.
+* Otherwise falls back to Vite's built-in preview server.
+*/
+async function runPreview(options) {
+	const { join } = await import("node:path");
+	const root = process.cwd();
+	const config = await loadTimberConfig(root).catch(() => null);
+	const adapter = config?.adapter;
+	if (resolvePreviewStrategy(adapter) === "adapter") {
+		const buildDir = join(root, ".timber", "build");
+		const timberConfig = { output: config?.output ?? "server" };
+		await adapter.preview(timberConfig, buildDir);
+		return;
+	}
+	const { preview } = await import("vite");
+	(await preview({ configFile: options.config })).printUrls();
+}
+/**
+* Validate types and routes without producing build output.
+* Runs tsgo --noEmit for type checking.
+*/
+async function runCheck(options) {
+	const { execFile } = await import("node:child_process");
+	await new Promise((resolve, reject) => {
+		execFile("tsgo", ["--noEmit", ...options.config ? ["--project", options.config] : []], (err, stdout, stderr) => {
+			if (stdout) process.stdout.write(stdout);
+			if (stderr) process.stderr.write(stderr);
+			if (err) reject(/* @__PURE__ */ new Error(`Type check failed with exit code ${err.code}`));
+			else resolve();
+		});
+	});
+}
+async function main() {
+	const parsed = parseArgs(process.argv.slice(2));
+	const options = { config: parsed.config };
+	switch (parsed.command) {
+		case "dev":
+			await runDev(options);
+			break;
+		case "build":
+			await runBuild(options);
+			break;
+		case "preview":
+			await runPreview(options);
+			break;
+		case "check":
+			await runCheck(options);
+			break;
+	}
+}
+if (typeof process !== "undefined" && process.argv[1] && import.meta.url.endsWith(process.argv[1])) main().catch((err) => {
+	console.error(err.message);
+	process.exit(1);
+});
+//#endregion
+export { parseArgs, resolvePreviewStrategy, runBuild, runCheck, runDev, runPreview };
+
+//# sourceMappingURL=cli.js.map