veryfront 0.1.89 → 0.1.90

package/src/deno.js

@@ -1,6 +1,6 @@
 export default {
   "name": "veryfront",
-  "version": "0.1.89",
+  "version": "0.1.90",
   "license": "Apache-2.0",
   "nodeModulesDir": "auto",
   "exclude": [

package/src/src/html/styles-builder/candidate-extractor.ts

@@ -6,6 +6,9 @@
  * @module html/styles-builder/candidate-extractor
  */
 
+import type { StyleScopeProfile } from "./style-scope-profile.js";
+import { shouldIncludeStylePath } from "./style-scope-profile.js";
+
 /**
  * Extract potential Tailwind class name candidates from source code content.
  * Uses a comprehensive regex pattern matching Tailwind v4 utility patterns.
@@ -17,12 +20,22 @@ export function extractCandidates(content: string): string[] {
 
 export function extractCandidatesFromFiles(
   files: Array<{ path: string; content?: string }>,
+  options: {
+    projectDir?: string;
+    styleProfile?: StyleScopeProfile;
+  } = {},
 ): Set<string> {
   const candidates = new Set<string>();
   const sourceExtensions = [".tsx", ".jsx", ".ts", ".js", ".mdx"];
 
   for (const file of files) {
     if (!file.content) continue;
+    if (
+      options.styleProfile &&
+      !shouldIncludeStylePath(options.styleProfile, file.path, options.projectDir)
+    ) {
+      continue;
+    }
     if (!sourceExtensions.some((ext) => file.path.endsWith(ext))) continue;
 
     for (const candidate of extractCandidates(file.content)) {

package/src/src/html/styles-builder/content-version.ts

@@ -0,0 +1,20 @@
+import type { ResolvedContentContext } from "../../platform/adapters/fs/veryfront/types.js";
+
+interface ContentVersionFallback {
+  releaseId?: string | null;
+  branch?: string | null;
+  environmentName?: string | null;
+}
+
+export function resolveStyleContentVersion(
+  contentContext: ResolvedContentContext | null,
+  fallback: ContentVersionFallback = {},
+): string {
+  if (contentContext?.releaseId) return `release:${contentContext.releaseId}`;
+  if (contentContext?.branch) return `branch:${contentContext.branch}`;
+  if (contentContext?.environmentName) return `environment:${contentContext.environmentName}`;
+  if (fallback.releaseId) return `release:${fallback.releaseId}`;
+  if (fallback.branch) return `branch:${fallback.branch}`;
+  if (fallback.environmentName) return `environment:${fallback.environmentName}`;
+  return "live";
+}

package/src/src/html/styles-builder/css-pregeneration.ts

@@ -8,20 +8,35 @@
 
 import { serverLogger } from "../../utils/index.js";
 import { extractCandidatesFromFiles, getProjectCSS } from "./tailwind-compiler.js";
+import {
+  createPreparedProjectCSSContext,
+  storePreparedProjectCSS,
+} from "./prepared-project-css-cache.js";
+import type { StyleScopeProfile } from "./style-scope-profile.js";
 
 const logger = serverLogger.component("css-pregeneration");
 
 interface CSSPregenerationOptions {
   /** Project slug for cache keying */
   projectSlug: string;
+  /** Current content version for the prepared stylesheet artifact */
+  projectVersion: string;
+  /** Project root used for style scope filtering */
+  projectDir?: string;
   /** List of files with content to extract candidates from */
   files: Array<{ path: string; content?: string }>;
+  /** Style scope profile for convention-based filtering */
+  styleProfile: StyleScopeProfile;
   /** Optional custom stylesheet (globals.css content) */
   stylesheet?: string;
   /** Optional stylesheet path (from config) to locate content in files */
   stylesheetPath?: string;
   /** Enable minification (default: true) */
   minify?: boolean;
+  /** Environment segment used for prepared artifact cache partitioning */
+  environment?: string;
+  /** Build mode recorded in the prepared artifact profile */
+  buildMode?: "development" | "production";
 }
 
 /**
@@ -39,34 +54,56 @@ interface CSSPregenerationOptions {
 export async function pregenerateCSSFromFiles(
   options: CSSPregenerationOptions,
 ): Promise<void> {
-  const { projectSlug, files, stylesheet, stylesheetPath, minify = true } = options;
+  const {
+    projectSlug,
+    projectVersion,
+    projectDir,
+    files,
+    styleProfile,
+    stylesheet,
+    stylesheetPath,
+    minify = true,
+    environment = "preview",
+    buildMode = "production",
+  } = options;
   const startTime = performance.now();
 
   try {
-    const candidates = extractCandidatesFromFiles(files);
-
-    if (candidates.size === 0) {
-      logger.debug("No candidates found, skipping", {
-        projectSlug,
-        fileCount: files.length,
-      });
-      return;
-    }
-
     const resolvedStylesheet = stylesheet ?? findStylesheetFromFiles(files, stylesheetPath);
+    const candidates = extractCandidatesFromFiles(files, {
+      projectDir,
+      styleProfile,
+    });
 
     logger.debug("Starting", {
       projectSlug,
+      projectVersion,
       fileCount: files.length,
       candidateCount: candidates.size,
       hasStylesheet: Boolean(resolvedStylesheet),
+      styleProfileHash: styleProfile.hash,
     });
 
-    const result = await getProjectCSS(projectSlug, resolvedStylesheet, candidates, { minify });
+    const result = await getProjectCSS(projectSlug, resolvedStylesheet, candidates, {
+      minify,
+      environment,
+      buildMode,
+    });
+    await storePreparedProjectCSS(
+      createPreparedProjectCSSContext(
+        projectSlug,
+        projectVersion,
+        resolvedStylesheet,
+        styleProfile.hash,
+        { minify, environment, buildMode },
+      ),
+      { css: result.css, hash: result.hash },
+    );
     const duration = performance.now() - startTime;
 
     logger.debug("Complete", {
       projectSlug,
+      projectVersion,
       candidateCount: candidates.size,
       cssLength: result.css.length,
       cssHash: result.hash,

package/src/src/html/styles-builder/prepared-project-css-cache.ts

@@ -0,0 +1,228 @@
+import {
+  type CacheBackend,
+  createCacheBackend,
+  MemoryCacheBackend,
+} from "../../cache/backend.js";
+import { registerCache } from "../../utils/memory/index.js";
+import { serverLogger } from "../../utils/index.js";
+import { DEFAULT_STYLESHEET } from "./css-hash-cache.js";
+import { resolveStylesheet } from "./tailwind-compiler-utils.js";
+
+const logger = serverLogger.component("prepared-project-css-cache");
+
+interface PreparedProjectCSSCacheEntry {
+  css: string;
+  hash: string;
+}
+
+interface PreparedProjectCSSLocalEntry extends PreparedProjectCSSCacheEntry {
+  expiresAt: number;
+}
+
+interface PreparedProjectCSSProfile {
+  minify?: boolean;
+  environment?: string;
+  buildMode?: "development" | "production";
+}
+
+export interface PreparedProjectCSSRequestContext {
+  projectSlug: string;
+  projectVersion: string;
+  stylesheet: string;
+  stylesheetHash: string;
+  styleProfileHash: string;
+  environment: string;
+  profileHash: string;
+  cacheKey: string;
+}
+
+const PREPARED_PROJECT_CSS_CACHE_TTL_SECONDS = 24 * 3600;
+const PREPARED_PROJECT_CSS_LOCAL_MAX = 50;
+const PREPARED_PROJECT_CSS_LOCAL_TTL_MS = PREPARED_PROJECT_CSS_CACHE_TTL_SECONDS * 1000;
+
+let preparedProjectCSSBackend: CacheBackend | null = null;
+let preparedProjectCSSInitialized = false;
+let preparedProjectCSSInitPromise: Promise<void> | null = null;
+
+const localPreparedProjectCSS = new Map<string, PreparedProjectCSSLocalEntry>();
+
+registerCache("prepared-project-css-cache", () => ({
+  name: "prepared-project-css-cache",
+  entries: localPreparedProjectCSS.size,
+  maxEntries: PREPARED_PROJECT_CSS_LOCAL_MAX,
+  backend: preparedProjectCSSBackend?.type ?? "uninitialized",
+}));
+
+function hashValue(input: string): string {
+  let hash = 0;
+  for (let index = 0; index < input.length; index++) {
+    hash = ((hash << 5) - hash) + input.charCodeAt(index);
+    hash |= 0;
+  }
+  return hash.toString(36);
+}
+
+function setLocalEntry(key: string, entry: PreparedProjectCSSCacheEntry): void {
+  localPreparedProjectCSS.set(key, {
+    ...entry,
+    expiresAt: Date.now() + PREPARED_PROJECT_CSS_LOCAL_TTL_MS,
+  });
+
+  if (localPreparedProjectCSS.size <= PREPARED_PROJECT_CSS_LOCAL_MAX) return;
+
+  const keys = localPreparedProjectCSS.keys();
+  while (localPreparedProjectCSS.size > PREPARED_PROJECT_CSS_LOCAL_MAX) {
+    const result = keys.next();
+    if (result.done) break;
+    localPreparedProjectCSS.delete(result.value);
+  }
+}
+
+function parsePreparedProjectCSSCacheEntry(
+  raw: string,
+): PreparedProjectCSSCacheEntry | null {
+  try {
+    const parsed = JSON.parse(raw) as Partial<PreparedProjectCSSCacheEntry>;
+    if (typeof parsed.css !== "string" || typeof parsed.hash !== "string") return null;
+    return { css: parsed.css, hash: parsed.hash };
+  } catch {
+    return null;
+  }
+}
+
+export async function initializePreparedProjectCSSCache(): Promise<boolean> {
+  if (preparedProjectCSSInitialized) return preparedProjectCSSBackend?.type !== "memory";
+
+  if (!preparedProjectCSSInitPromise) {
+    preparedProjectCSSInitPromise = (async () => {
+      try {
+        preparedProjectCSSBackend = await createCacheBackend({
+          keyPrefix: "prepared-project-css",
+        });
+        logger.debug("Initialized", { backend: preparedProjectCSSBackend.type });
+      } catch (error) {
+        logger.warn("Backend init failed, using memory", { error });
+        preparedProjectCSSBackend = new MemoryCacheBackend(PREPARED_PROJECT_CSS_LOCAL_MAX);
+      } finally {
+        preparedProjectCSSInitialized = true;
+      }
+    })();
+  }
+
+  await preparedProjectCSSInitPromise;
+  preparedProjectCSSInitPromise = null;
+
+  return preparedProjectCSSBackend?.type !== "memory";
+}
+
+export function createPreparedProjectCSSContext(
+  projectSlug: string,
+  projectVersion: string,
+  stylesheet: string | undefined,
+  styleProfileHash: string,
+  profile?: PreparedProjectCSSProfile,
+): PreparedProjectCSSRequestContext {
+  const resolvedStylesheet = resolveStylesheet(stylesheet, DEFAULT_STYLESHEET);
+  const stylesheetHash = hashValue(resolvedStylesheet);
+  const environment = profile?.environment ?? "preview";
+  const profileHash = hashValue(
+    JSON.stringify({
+      cacheSchema: "v1",
+      minify: profile?.minify ?? false,
+      buildMode: profile?.buildMode ?? "production",
+      environment,
+    }),
+  );
+
+  return {
+    projectSlug,
+    projectVersion,
+    stylesheet: resolvedStylesheet,
+    stylesheetHash,
+    styleProfileHash,
+    environment,
+    profileHash,
+    cacheKey:
+      `${projectSlug}:${environment}:prepared:${projectVersion}:${stylesheetHash}:${styleProfileHash}:${profileHash}`,
+  };
+}
+
+export async function tryGetPreparedProjectCSS(
+  context: PreparedProjectCSSRequestContext,
+): Promise<{ css: string; hash: string; fromCache: true } | undefined> {
+  const local = localPreparedProjectCSS.get(context.cacheKey);
+  if (local && local.expiresAt > Date.now()) {
+    return { css: local.css, hash: local.hash, fromCache: true };
+  }
+
+  if (local) {
+    localPreparedProjectCSS.delete(context.cacheKey);
+  }
+
+  if (!preparedProjectCSSInitialized) {
+    await initializePreparedProjectCSSCache();
+  }
+
+  if (!preparedProjectCSSBackend) return undefined;
+
+  try {
+    const raw = await preparedProjectCSSBackend.get(context.cacheKey);
+    if (!raw) return undefined;
+
+    const entry = parsePreparedProjectCSSCacheEntry(raw);
+    if (!entry) return undefined;
+
+    setLocalEntry(context.cacheKey, entry);
+    return { css: entry.css, hash: entry.hash, fromCache: true };
+  } catch (error) {
+    logger.debug("Failed to read prepared project CSS", {
+      cacheKey: context.cacheKey,
+      error,
+    });
+    return undefined;
+  }
+}
+
+export async function storePreparedProjectCSS(
+  context: PreparedProjectCSSRequestContext,
+  entry: PreparedProjectCSSCacheEntry,
+): Promise<void> {
+  if (!preparedProjectCSSInitialized) {
+    await initializePreparedProjectCSSCache();
+  }
+
+  setLocalEntry(context.cacheKey, entry);
+
+  if (!preparedProjectCSSBackend) return;
+
+  preparedProjectCSSBackend
+    .set(context.cacheKey, JSON.stringify(entry), PREPARED_PROJECT_CSS_CACHE_TTL_SECONDS)
+    .catch((error) => {
+      logger.debug("Failed to store prepared project CSS", {
+        cacheKey: context.cacheKey,
+        error,
+      });
+    });
+}
+
+export function invalidatePreparedProjectCSS(projectSlug: string): void {
+  for (const key of localPreparedProjectCSS.keys()) {
+    if (key.startsWith(`${projectSlug}:`)) {
+      localPreparedProjectCSS.delete(key);
+    }
+  }
+
+  invalidatePreparedProjectCSSAsync(projectSlug).catch((error) => {
+    logger.debug("Failed to invalidate prepared project CSS", { projectSlug, error });
+  });
+}
+
+export async function invalidatePreparedProjectCSSAsync(projectSlug: string): Promise<void> {
+  if (!preparedProjectCSSBackend?.delByPattern) return;
+
+  try {
+    await preparedProjectCSSBackend.delByPattern(`${projectSlug}:*`);
+  } catch (error) {
+    logger.debug("Failed to delete prepared project CSS", { projectSlug, error });
+  }
+}

package/src/src/html/styles-builder/style-scope-profile.ts

@@ -0,0 +1,164 @@
+import type { VeryfrontConfig } from "../../config/index.js";
+
+const DEFAULT_IGNORED_ROOTS = [
+  "knowledge",
+  "coverage",
+  "dist",
+  "build",
+  ".git",
+  "node_modules",
+  ".cache",
+];
+
+const DEFAULT_PROTECTED_ROOTS = [
+  "app",
+  "pages",
+  "components",
+  "src/app",
+  "src/pages",
+  "src/components",
+];
+
+export interface StyleScopeProfile {
+  hash: string;
+  ignoredRoots: string[];
+  protectedRoots: string[];
+  protectedPaths: string[];
+}
+
+function normalizePath(path: string): string {
+  return path.replace(/\\/g, "/").replace(/\/{2,}/g, "/");
+}
+
+function normalizeRelativePath(path: string): string {
+  return normalizePath(path).replace(/^\/+/, "").replace(/\/+$/, "");
+}
+
+function toRelativeProjectPath(path: string, projectDir?: string): string {
+  const normalized = normalizePath(path);
+  const normalizedProjectDir = projectDir
+    ? normalizePath(projectDir).replace(/\/+$/, "")
+    : undefined;
+
+  if (normalizedProjectDir && normalized.startsWith(normalizedProjectDir)) {
+    return normalized.slice(normalizedProjectDir.length).replace(/^\/+/, "");
+  }
+
+  return normalized.replace(/^\/+/, "");
+}
+
+function isWithinPath(path: string, root: string): boolean {
+  return path === root || path.startsWith(`${root}/`);
+}
+
+function getParentDirectory(path: string): string | null {
+  const normalized = normalizeRelativePath(path);
+  const slashIndex = normalized.lastIndexOf("/");
+  if (slashIndex <= 0) return null;
+  return normalized.slice(0, slashIndex);
+}
+
+function stableHash(input: string): string {
+  let hash = 0;
+  for (let index = 0; index < input.length; index++) {
+    hash = ((hash << 5) - hash) + input.charCodeAt(index);
+    hash |= 0;
+  }
+  return hash.toString(36);
+}
+
+function addNormalizedPath(target: Set<string>, value: string | null | undefined): void {
+  if (!value) return;
+  const normalized = normalizeRelativePath(value);
+  if (!normalized) return;
+  target.add(normalized);
+}
+
+export function createStyleScopeProfile(config?: VeryfrontConfig): StyleScopeProfile {
+  const ignoredRoots = new Set<string>(DEFAULT_IGNORED_ROOTS);
+  const protectedRoots = new Set<string>(DEFAULT_PROTECTED_ROOTS);
+  const protectedPaths = new Set<string>();
+
+  addNormalizedPath(protectedRoots, config?.directories?.app);
+  addNormalizedPath(protectedRoots, config?.directories?.pages);
+
+  for (const path of config?.directories?.components ?? []) {
+    addNormalizedPath(protectedRoots, path);
+  }
+
+  const explicitPaths = [
+    typeof config?.layout === "string" ? config.layout : undefined,
+    typeof config?.app === "string" ? config.app : undefined,
+    config?.tailwind?.stylesheet,
+  ];
+
+  for (const path of explicitPaths) {
+    addNormalizedPath(protectedPaths, path);
+    addNormalizedPath(protectedRoots, getParentDirectory(path ?? ""));
+  }
+
+  for (const root of protectedRoots) {
+    ignoredRoots.delete(root);
+  }
+
+  const sortedIgnoredRoots = [...ignoredRoots].sort();
+  const sortedProtectedRoots = [...protectedRoots].sort();
+  const sortedProtectedPaths = [...protectedPaths].sort();
+
+  return {
+    ignoredRoots: sortedIgnoredRoots,
+    protectedRoots: sortedProtectedRoots,
+    protectedPaths: sortedProtectedPaths,
+    hash: stableHash(
+      JSON.stringify({
+        ignoredRoots: sortedIgnoredRoots,
+        protectedRoots: sortedProtectedRoots,
+        protectedPaths: sortedProtectedPaths,
+      }),
+    ),
+  };
+}
+
+function isProtectedPath(
+  profile: StyleScopeProfile,
+  relativePath: string,
+): boolean {
+  return profile.protectedPaths.some((path) => isWithinPath(relativePath, path)) ||
+    profile.protectedRoots.some((path) => isWithinPath(relativePath, path));
+}
+
+export function shouldIncludeStylePath(
+  profile: StyleScopeProfile,
+  path: string,
+  projectDir?: string,
+): boolean {
+  const relativePath = normalizeRelativePath(toRelativeProjectPath(path, projectDir));
+  if (!relativePath) return true;
+  if (isProtectedPath(profile, relativePath)) return true;
+
+  return !profile.ignoredRoots.some((root) => isWithinPath(relativePath, root));
+}
+
+export function shouldTraverseStyleDirectory(
+  profile: StyleScopeProfile,
+  directoryPath: string,
+  projectDir?: string,
+): boolean {
+  const relativePath = normalizeRelativePath(toRelativeProjectPath(directoryPath, projectDir));
+  if (!relativePath) return true;
+  if (isProtectedPath(profile, relativePath)) return true;
+
+  const ignoredRoot = profile.ignoredRoots.find((root) => isWithinPath(relativePath, root));
+  if (!ignoredRoot) return true;
+
+  return profile.protectedRoots.some((root) => isWithinPath(root, relativePath)) ||
+    profile.protectedPaths.some((path) => isWithinPath(path, relativePath));
+}
+
+export function filterFilesForStyleScope<T extends { path: string }>(
+  files: T[],
+  profile: StyleScopeProfile,
+  projectDir?: string,
+): T[] {
+  return files.filter((file) => shouldIncludeStylePath(profile, file.path, projectDir));
+}

package/src/src/platform/adapters/fs/factory.ts

@@ -1,19 +1,7 @@
 import type { FSAdapter, FSAdapterConfig } from "./veryfront/types.js";
 import { createError, toError } from "../../../errors/veryfront-error.js";
 import { withSpan } from "../../../observability/tracing/otlp-setup.js";
-import {
-  clearSSRModuleCache,
-  clearSSRModuleCacheForProject,
-} from "../../../modules/react-loader/ssr-module-loader/cache/index.js";
-import { clearRouterDetectionCacheForProject } from "../../../rendering/router-detection.js";
-import {
-  clearModulePathCache,
-  invalidateModulePaths,
-} from "../../../transforms/mdx/esm-module-loader/cache/index.js";
-import { clearSnippetCacheForProject } from "../../../rendering/snippet-renderer.js";
-import { clearRendererCacheForProject } from "../../../rendering/renderer.js";
-import { invalidateProjectCSS } from "../../../html/styles-builder/tailwind-compiler.js";
-import { invalidateProjectCandidateManifests } from "../../../rendering/orchestrator/css-candidate-manifest.js";
+import { createDefaultInvalidationCallbacks } from "./veryfront/default-invalidation-callbacks.js";
 
 export function createFSAdapter(config: FSAdapterConfig): Promise<FSAdapter> {
   const type = config.type ?? "local";
@@ -36,20 +24,7 @@ export function createFSAdapter(config: FSAdapterConfig): Promise<FSAdapter> {
       if (type === "veryfront-api") {
         const configWithCallbacks: FSAdapterConfig = {
           ...config,
-          invalidationCallbacks: {
-            clearSSRModuleCache,
-            clearModulePathCache,
-            invalidateModulePaths,
-            clearSSRModuleCacheForProject,
-            clearRouterDetectionCacheForProject,
-            clearSnippetCacheForProject,
-            clearRendererCacheForProject,
-            clearProjectCSSCache: (projectSlug: string) => {
-              invalidateProjectCSS(projectSlug);
-              invalidateProjectCandidateManifests(projectSlug);
-            },
-            ...config.invalidationCallbacks,
-          },
+          invalidationCallbacks: createDefaultInvalidationCallbacks(config.invalidationCallbacks),
         };
 
         if (proxyMode) {