veryfront 0.1.49 → 0.1.50

package/src/src/discovery/import-rewriter.ts

@@ -114,7 +114,8 @@ export async function rewriteDiscoveryImports(
               "index.js";
 
           return pathToFileURL(pathHelper.join(packagePath, entryPoint)).href;
-        } catch {
+        } catch (_) {
+          /* expected: package.json not found at this level, walk up */
           const parent = pathHelper.dirname(searchDir);
           if (parent === searchDir) break;
           searchDir = parent;
@@ -164,7 +165,8 @@ export async function rewriteDiscoveryImports(
       const vfPackageJsonPath = pathHelper.join(vfPackagePath, "package.json");
       const pkgJson = JSON.parse(await fs.readTextFile(vfPackageJsonPath));
       exportsMap = pkgJson.exports || {};
-    } catch {
+    } catch (_) {
+      /* expected: veryfront package.json not found, fallback to deno.json search */
       // Search for deno.json in parent directories
       let searchDir = projectDir;
 
@@ -177,8 +179,8 @@ export async function rewriteDiscoveryImports(
             vfPackagePath = searchDir;
             break;
           }
-        } catch {
-          // continue searching
+        } catch (_) {
+          /* expected: deno.json not found at this level */
         }
         searchDir = pathHelper.dirname(searchDir);
       }
@@ -211,7 +213,8 @@ export async function rewriteDiscoveryImports(
       const resolvedPath = pathHelper.join(vfPackagePath, exportPath);
       return `from "${pathToFileURL(resolvedPath).href}"`;
     });
-  } catch {
+  } catch (_) {
+    /* expected: Node.js URL module unavailable in non-Node runtime */
     return transformed;
   }
 

package/src/src/discovery/transpiler.ts

@@ -15,6 +15,7 @@ import { getEsbuildLoader } from "../utils/path-utils.js";
 import type { FileSystemAdapter } from "../platform/adapters/base.js";
 import type { FileDiscoveryContext } from "./types.js";
 import { rewriteDiscoveryImports, rewriteForDeno } from "./import-rewriter.js";
+import { COMPILATION_ERROR, FILE_NOT_FOUND } from "../errors/index.js";
 import { wrapWithCurrentContext } from "../platform/adapters/fs/veryfront/multi-project-adapter.js";
 // Static import ensures deno compile includes embedding in the binary.
 // Other modules (agent, tool, etc.) are statically imported elsewhere;
@@ -159,7 +160,10 @@ export async function importModule(
       ? await context.fsAdapter.readFile(filePath)
       : await createFileSystem().readTextFile(filePath);
   } catch (error) {
-    throw new Error(`Failed to read file ${filePath}: ${error}`);
+    throw FILE_NOT_FOUND.create({
+      detail: `Failed to read file ${filePath}: ${error}`,
+      cause: error,
+    });
   }
 
   const loader = getEsbuildLoader(filePath);
@@ -208,9 +212,9 @@ export async function importModule(
   });
 
   if (result.errors.length > 0) {
-    throw new Error(
-      `Failed to transpile ${filePath}: ${result.errors[0]?.text ?? "unknown error"}`,
-    );
+    throw COMPILATION_ERROR.create({
+      detail: `Failed to transpile ${filePath}: ${result.errors[0]?.text ?? "unknown error"}`,
+    });
   }
 
   const js = result.outputFiles?.[0]?.text ?? "export {}";

package/src/src/embedding/chunk.ts

@@ -1,5 +1,11 @@
 import type { ChunkOptions } from "./types.js";
 
+/** Default maximum characters per chunk (~512 tokens). */
+const DEFAULT_CHUNK_MAX_CHARS = 2_000;
+
+/** Default character overlap between consecutive chunks. */
+const DEFAULT_CHUNK_OVERLAP = 200;
+
 /**
  * Splits text into overlapping chunks for embedding.
  *
@@ -16,8 +22,8 @@ import type { ChunkOptions } from "./types.js";
  * ```
  */
 export async function chunk(text: string, options?: ChunkOptions): Promise<string[]> {
-  const maxChars = options?.maxChars ?? 2000;
-  const overlap = options?.overlap ?? 200;
+  const maxChars = options?.maxChars ?? DEFAULT_CHUNK_MAX_CHARS;
+  const overlap = options?.overlap ?? DEFAULT_CHUNK_OVERLAP;
   const separators = options?.separators ?? ["\n\n", "\n", " ", ""];
 
   return splitRecursive(text, separators, maxChars, overlap);

package/src/src/embedding/react/use-uploads.ts

@@ -9,6 +9,7 @@ import * as dntShim from "../../../_dnt.shims.js";
 
 import { useCallback, useEffect, useRef, useState } from "react";
 import type { UploadMeta } from "../types.js";
+import { API_ERROR } from "../../errors/index.js";
 
 export interface UseUploadsOptions {
   /** API endpoint, e.g. "/api/uploads" */
@@ -45,7 +46,8 @@ export function useUploads(options: UseUploadsOptions): UseUploadsResult {
       if (!res.ok) return;
       const data = await res.json();
       setUploads(data.uploads ?? []);
-    } catch {
+    } catch (error) {
+      console.debug("useUploads: failed to load uploads", error);
       setError("Failed to load uploads");
     }
   }, [options.api]);
@@ -71,7 +73,7 @@ export function useUploads(options: UseUploadsOptions): UseUploadsResult {
           signal: abortController.signal,
         });
         const data = await res.json();
-        if (!res.ok) throw new Error(data.error ?? "Upload failed");
+        if (!res.ok) throw API_ERROR.create({ detail: data.error ?? "Upload failed" });
         await refresh();
       } catch (err) {
         if (err instanceof Error && err.name === "AbortError") return;
@@ -90,7 +92,8 @@ export function useUploads(options: UseUploadsOptions): UseUploadsResult {
       try {
         await dntShim.fetch(`${options.api}/${id}`, { method: "DELETE" });
         await refresh();
-      } catch {
+      } catch (error) {
+        console.debug("useUploads: failed to delete upload", error);
         setError("Failed to delete upload");
       }
     },

package/src/src/embedding/resolve.ts

@@ -5,7 +5,7 @@ import { createGoogleGenerativeAI } from "@ai-sdk/google";
 import { getGoogleGenAIEnvConfig, getOpenAIEnvConfig } from "../config/env.js";
 import { createLocalEmbeddingModel } from "../provider/local/local-embedding-adapter.js";
 
-export type EmbeddingProviderFactory = (modelId: string) => EmbeddingModel;
+type EmbeddingProviderFactory = (modelId: string) => EmbeddingModel;
 
 const providers = new Map<string, EmbeddingProviderFactory>();
 let autoInitialized = false;

package/src/src/embedding/upload-handler.ts

@@ -1,8 +1,10 @@
 import * as dntShim from "../../_dnt.shims.js";
+import { serverLogger } from "../utils/index.js";
 import type { UploadStore } from "./types.js";
 import { loadUpload } from "./upload-loader.js";
 
 const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10 MB
+const MAX_FILE_NAME_LENGTH = 200;
 
 const MIME_TO_TYPE: Record<string, string> = {
   "text/plain": "txt",
@@ -132,7 +134,7 @@ export function createUploadHandler(
       }
 
       // Sanitize file name: strip path components, limit length
-      const safeName = file.name.replace(/[/\\]/g, "_").slice(0, 200);
+      const safeName = file.name.replace(/[/\\]/g, "_").slice(0, MAX_FILE_NAME_LENGTH);
 
       const id = await store.ingest(safeName, text, {
         source: `upload:${safeName}`,
@@ -154,7 +156,7 @@ export function createUploadHandler(
       const uploads = await store.listUploads();
       return dntShim.Response.json({ uploads });
     } catch (error) {
-      console.error("Upload list failed:", error);
+      serverLogger.error("Upload list failed:", error);
       return dntShim.Response.json({ error: "Failed to list uploads" }, { status: 500 });
     }
   }
@@ -171,7 +173,7 @@ export function createUploadHandler(
       await store.removeUpload(id);
       return dntShim.Response.json({ success: true });
     } catch (error) {
-      console.error("Upload delete failed:", error);
+      serverLogger.error("Upload delete failed:", error);
       return dntShim.Response.json({ error: "Delete failed" }, { status: 500 });
     }
   }

package/src/src/embedding/upload-loader.ts

@@ -38,7 +38,7 @@ function extractCSV(buffer: ArrayBuffer): string {
   const lines = text.split("\n").filter((line) => line.trim());
   if (lines.length < 2) return text;
 
-  const headers = parseCSVLine(lines[0]!);
+  const headers = parseCSVLine(lines[0] ?? "");
   const rows = lines.slice(1).map((line) => {
     const values = parseCSVLine(line);
     return headers

package/src/src/embedding/upload-store.ts

@@ -8,6 +8,7 @@ import {
   writeTextFile,
 } from "../platform/compat/fs.js";
 import { dirname, extname, join } from "../platform/compat/path/basic-operations.js";
+import { serverLogger } from "../utils/index.js";
 import { embedding } from "./embedding.js";
 import { chunk } from "./chunk.js";
 import type {
@@ -19,6 +20,10 @@ import type {
   UploadStoreConfig,
   UploadStoreData,
 } from "./types.js";
+import { INVALID_ARGUMENT } from "../errors/index.js";
+
+/** Default number of top results returned by similarity search. */
+const DEFAULT_TOP_K = 5;
 
 /**
  * Creates a persistent upload store with lazy embedding and similarity search.
@@ -59,7 +64,7 @@ export function uploadStore(config: UploadStoreConfig): UploadStore {
     mutex = result.then(
       () => {},
       (err) => {
-        console.error("[upload-store] Lock operation failed:", err);
+        serverLogger.error("[upload-store] Lock operation failed:", err);
       },
     );
     return result;
@@ -77,7 +82,7 @@ export function uploadStore(config: UploadStoreConfig): UploadStore {
       const data = await readTextFile(storagePath);
       const parsed = JSON.parse(data);
       if (!parsed || !Array.isArray(parsed.uploads) || !Array.isArray(parsed.chunks)) {
-        console.warn("[upload-store] Corrupted store file, resetting:", storagePath);
+        serverLogger.warn("[upload-store] Corrupted store file, resetting", { storagePath });
         return { uploads: [], chunks: [] };
       }
       return parsed as UploadStoreData;
@@ -86,7 +91,7 @@ export function uploadStore(config: UploadStoreConfig): UploadStore {
       if (isNotFoundError(err)) {
         return { uploads: [], chunks: [] };
       }
-      console.warn("[upload-store] Failed to load store, resetting:", err);
+      serverLogger.warn("[upload-store] Failed to load store, resetting", err);
       return { uploads: [], chunks: [] };
     }
   }
@@ -107,8 +112,8 @@ export function uploadStore(config: UploadStoreConfig): UploadStore {
         const fs = await import("node:fs/promises");
         await fs.rename(tmpPath, storagePath);
       }
-    } catch {
-      // Fallback for environments where rename isn't available
+    } catch (_) {
+      // expected: rename not available in all environments, fall back to direct write
       await writeTextFile(storagePath, payload);
     }
   }
@@ -135,8 +140,8 @@ export function uploadStore(config: UploadStoreConfig): UploadStore {
           files.push(fullPath);
         }
       }
-    } catch {
-      // directory may not exist yet
+    } catch (_) {
+      // expected: directory may not exist yet
     }
     return files;
   }
@@ -152,14 +157,14 @@ export function uploadStore(config: UploadStoreConfig): UploadStore {
         const uploadId = dntShim.crypto.randomUUID();
 
         if (text.length > MAX_TEXT_LENGTH) {
-          throw new Error(
-            `Upload text exceeds ${MAX_TEXT_LENGTH / 1024 / 1024} MB limit`,
-          );
+          throw INVALID_ARGUMENT.create({
+            detail: `Upload text exceeds ${MAX_TEXT_LENGTH / 1024 / 1024} MB limit`,
+          });
         }
 
         const chunks = await chunk(text, chunkOptions);
         if (chunks.length === 0) {
-          throw new Error("Upload contains no extractable text");
+          throw INVALID_ARGUMENT.create({ detail: "Upload contains no extractable text" });
         }
 
         const doc: UploadMeta = {
@@ -198,7 +203,7 @@ export function uploadStore(config: UploadStoreConfig): UploadStore {
         if (updated) await save(data);
 
         const queryEmbedding = await embedder.embed(query);
-        const topK = options?.topK ?? 5;
+        const topK = options?.topK ?? DEFAULT_TOP_K;
         const threshold = options?.threshold;
 
         const docMap = new Map(data.uploads.map((d) => [d.id, d]));
@@ -256,7 +261,7 @@ export function uploadStore(config: UploadStoreConfig): UploadStore {
           const content = await readTextFile(file);
           if (!content?.trim()) continue;
           if (content.length > MAX_TEXT_LENGTH) {
-            console.warn(
+            serverLogger.warn(
               `[upload-store] Skipping ${file}: exceeds ${
                 MAX_TEXT_LENGTH / 1024 / 1024
               } MB text limit`,

package/src/src/errors/catalog/general-errors.ts

@@ -36,6 +36,17 @@ export const GENERAL_ERROR_CATALOG: PartialErrorCatalog = {
     ],
   ),
 
+  "resource-not-found": createSimpleError(
+    "resource-not-found",
+    "Resource not found",
+    "The requested resource does not exist.",
+    [
+      "Verify the referenced workflow, run, approval, or tool ID",
+      "Check for typos in the resource name",
+      "Confirm the resource has not been deleted",
+    ],
+  ),
+
   "invalid-argument": createSimpleError(
     "invalid-argument",
     "Invalid argument",

package/src/src/errors/error-context.ts

@@ -1,5 +1,8 @@
 /******** Structured error handling with logging for silent failure operations */
 
+// NOTE: serverLogger is imported but only accessed inside function bodies (never at
+// module-eval time). This is safe even with circular deps because by the time any
+// function in this module is called, all modules have finished initializing.
 import { serverLogger } from "../utils/logger/logger.js";
 import { getErrorMessage } from "./veryfront-error.js";
 

package/src/src/errors/error-handlers.ts

@@ -13,8 +13,8 @@ function safeLog(logFn: () => void): void {
   } catch (error) {
     try {
       logger.warn("Logging failed:", error);
-    } catch {
-      // Silently ignore if even warning fails
+    } catch (_) {
+      // expected: last-resort fallback; nothing left to do if logging itself fails
     }
   }
 }
@@ -75,6 +75,7 @@ export async function retryWithBackoff<T>(
         continue;
       }
 
+      // no cleanup needed: one-shot
       await new Promise<void>((resolve) => dntShim.setTimeout(resolve, delay));
       delay = Math.min(delay * 2, maxDelay);
     }

package/src/src/errors/error-registry.ts

@@ -619,6 +619,14 @@ export const FILE_NOT_FOUND = defineError({
   suggestion: "Verify the file path exists",
 });
 
+export const RESOURCE_NOT_FOUND = defineError({
+  slug: "resource-not-found",
+  category: "GENERAL",
+  status: 404,
+  title: "Requested resource not found",
+  suggestion: "Verify the referenced resource ID or name exists",
+});
+
 export const INVALID_ARGUMENT = defineError({
   slug: "invalid-argument",
   category: "GENERAL",
@@ -769,6 +777,7 @@ export const ERROR_REGISTRY = {
   "unknown-error": UNKNOWN_ERROR,
   "permission-denied": PERMISSION_DENIED,
   "file-not-found": FILE_NOT_FOUND,
+  "resource-not-found": RESOURCE_NOT_FOUND,
   "invalid-argument": INVALID_ARGUMENT,
   "timeout-error": TIMEOUT_ERROR,
   "initialization-error": INITIALIZATION_ERROR,

package/src/src/errors/index.ts

@@ -93,6 +93,7 @@ export {
   RELEASE_NOT_FOUND,
   RENDER_ERROR,
   REQUEST_ERROR,
+  RESOURCE_NOT_FOUND,
   // ROUTE
   ROUTE_CONFLICT,
   ROUTE_HANDLER_INVALID,

package/src/src/errors/logging.ts

@@ -6,6 +6,7 @@
  */
 
 import { isProduction } from "../build/config/environment.js";
+import { serverLogger } from "../utils/logger/logger.js";
 import { VeryfrontError } from "./types.js";
 
 export interface ErrorLogEntry {
@@ -50,23 +51,24 @@ export function logError(
   };
 
   if (isProduction()) {
-    // Structured JSON for log aggregation systems
+    // Direct JSON output — this module owns its own structured format
+    // (slug, category, status, docs) which differs from the logger envelope.
     console.error(JSON.stringify(entry));
   } else {
     // Human-readable format for development
-    console.error(`[ERROR] ${error.slug} (${error.category}) — ${error.title}`);
+    serverLogger.error(`[ERROR] ${error.slug} (${error.category}) — ${error.title}`);
     if (error.detail) {
-      console.error(`  Detail: ${error.detail}`);
+      serverLogger.error(`  Detail: ${error.detail}`);
     }
     if (error.suggestion) {
-      console.error(`  💡 Suggestion: ${error.suggestion}`);
+      serverLogger.error(`  💡 Suggestion: ${error.suggestion}`);
     }
-    console.error(`  📚 Docs: ${entry.docs}`);
+    serverLogger.error(`  📚 Docs: ${entry.docs}`);
     const mergedContext = context
       ? { ...(error.context as Record<string, unknown> ?? {}), ...context }
       : error.context;
     if (mergedContext) {
-      console.error(`  Context: ${JSON.stringify(mergedContext, null, 2)}`);
+      serverLogger.error(`  Context: ${JSON.stringify(mergedContext, null, 2)}`);
     }
   }
 }

package/src/src/errors/veryfront-error.ts

@@ -54,7 +54,7 @@ export interface FileContext {
   permissions?: string;
 }
 
-export interface NetworkContext {
+interface NetworkContext {
   url?: string;
   timeout?: number;
   retryCount?: number;
@@ -93,7 +93,6 @@ export const isBuildError = isErrorType("build");
 export const isAPIError = isErrorType("api");
 export const isRenderError = isErrorType("render");
 export const isConfigError = isErrorType("config");
-export const isAgentError = isErrorType("agent");
 export const isFileError = isErrorType("file");
 export const isNetworkError = isErrorType("network");
 

package/src/src/html/dev-scripts.ts

@@ -52,7 +52,7 @@ export function getProdScripts(slug: string, nonce?: string): string {
   <script type="module" src="/_veryfront/hydrate.js?slug=${encodedSlug}"${nonceAttr}></script>`;
 }
 
-export interface StudioScriptOptions {
+interface StudioScriptOptions {
   projectId: string;
   pageId: string;
   pagePath?: string;

package/src/src/html/hydration-script-builder/dev-error-logger.ts

@@ -21,7 +21,7 @@ export function generateDevErrorLoggerScript(nonce?: string): string {
               timestamp: new Date().toISOString()
             })
           }).catch(() => {});
-        } catch {}
+        } catch (_) { /* expected: fire-and-forget log, network errors ignored */ }
       };
 
       window.addEventListener('error', (event) => {

package/src/src/html/hydration-script-builder/dev-scripts.ts

@@ -16,7 +16,7 @@ function generateHMRScript(
   return `<script type="module" src="/_veryfront/hmr.js"${nonceAttr}></script>`;
 }
 
-export interface DevScriptsOptions {
+interface DevScriptsOptions {
   /** Skip hmr.js when preview-hmr.js will be used (proxy mode) */
   skipDevHMR?: boolean;
   /** Skip error logger when endpoint is not available (preview mode) */

package/src/src/html/hydration-script-builder/templates/renderer.ts

@@ -6,7 +6,8 @@ export const getRendererScript = () => `
         const input = typeof pathname === 'string' ? pathname : window.location.pathname;
         try {
           return new URL(input, window.location.origin).pathname || '/';
-        } catch {
+        } catch (_) {
+          /* expected: invalid URL input, fall back to string splitting */
           const [pathOnly] = String(input || '/').split(/[?#]/);
           return pathOnly || '/';
         }
@@ -155,8 +156,8 @@ export const getRendererScript = () => `
           window.history.replaceState({ pageData, scrollY: 0 }, '', window.location.href);
           log('Stored initial page data in history state');
         }
-      } catch {
-        // ignore parse errors
+      } catch (_) {
+        /* expected: hydration data JSON parse errors are non-critical */
       }
     }
 

package/src/src/html/hydration-script-builder/templates/router.ts

@@ -522,10 +522,10 @@ export const getRouterScript = () => `
       domain: window.location.origin,
       path: window.location.pathname,
       push: (path) => {
-        navigateSPA(path, true);
+        void navigateSPA(path, true);
       },
       replace: (path) => {
-        navigateSPA(path, false);
+        void navigateSPA(path, false);
       },
       back: () => {
         window.history.back();
@@ -608,7 +608,7 @@ export const getRouterScript = () => `
       }
 
       e.preventDefault();
-      navigateSPA(href, true);
+      void navigateSPA(href, true);
     });
 
     let currentHoverLink = null;
@@ -662,7 +662,8 @@ export const getRouterScript = () => `
     window.useRouter = () => {
       try {
         return useRouterFromModule();
-      } catch {
+      } catch (_) {
+        /* expected: useRouterFromModule may not be available, fall back to global router */
         return window.__veryfrontRouter;
       }
     };

package/src/src/html/styles-builder/css-hash-cache.ts

@@ -44,7 +44,7 @@ export interface CSSCacheEntry {
  * CSS inputs cache entry - stores the inputs needed to regenerate CSS.
  * Keyed by CSS hash, stores candidates and stylesheet for JIT regeneration.
  */
-export interface CSSInputsCacheEntry {
+interface CSSInputsCacheEntry {
   candidates: string[];
   stylesheet: string;
 }
@@ -78,27 +78,28 @@ interface DistributedCacheInitOptions {
   initFailureLog: string;
 }
 
-function getOrInitializeDistributedCache(
+async function getOrInitializeDistributedCache(
   options: DistributedCacheInitOptions,
 ): Promise<CacheBackend> {
   const existing = options.getCache();
-  if (existing) return Promise.resolve(existing);
+  if (existing) return existing;
 
   const pending = options.getCacheInitPromise();
   if (pending) return pending;
 
-  const initPromise = createCacheBackend({ keyPrefix: options.keyPrefix })
-    .then((backend) => {
+  const initPromise = (async () => {
+    try {
+      const backend = await createCacheBackend({ keyPrefix: options.keyPrefix });
       options.setCache(backend);
       logger.debug(options.initializedLog, { type: backend.type });
       return backend;
-    })
-    .catch((error) => {
+    } catch (error) {
       logger.warn(options.initFailureLog, { error });
       const fallback = new MemoryCacheBackend(options.localFallbackSize);
       options.setCache(fallback);
       return fallback;
-    });
+    }
+  })();
 
   options.setCacheInitPromise(initPromise);
   return initPromise;

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

@@ -11,7 +11,7 @@ import { extractCandidatesFromFiles, getProjectCSS } from "./tailwind-compiler.j
 
 const logger = serverLogger.component("css-pregeneration");
 
-export interface CSSPregenerationOptions {
+interface CSSPregenerationOptions {
   /** Project slug for cache keying */
   projectSlug: string;
   /** List of files with content to extract candidates from */

package/src/src/html/styles-builder/index.ts

@@ -11,7 +11,6 @@ export {
   extractCandidates,
   extractCandidatesFromFiles,
   formatCSSError,
-  generateTailwind4CSS,
   generateTailwindCSS,
   getCSSByHash,
   getProjectCSS,