evolit 0.1.0-alpha.14 → 0.1.0-alpha.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evolit",
-  "version": "0.1.0-alpha.14",
+  "version": "0.1.0-alpha.16",
   "description": "A convention-driven application framework for LitSX and web components.",
   "type": "module",
   "packageManager": "yarn@4.10.3",

package/src/cli.js

@@ -3,6 +3,7 @@
 import path from "node:path";
 import process from "node:process";
 import { scaffoldSite } from "./scaffold.js";
+import { terminal } from "./terminal.js";
 
 function parseArguments(argv) {
   const [command, ...rest] = argv;
@@ -24,9 +25,9 @@ function parseArguments(argv) {
 }
 
 function printUsage() {
-  console.log("Usage: evolit <directory>");
-  console.log("       evolit init <directory>");
-  console.log("       evolit <dev|build|start> [--port 3000]");
+  console.log(`${terminal.bold("Usage:")} evolit <directory>`);
+  console.log(`       evolit ${terminal.cyan("init")} <directory>`);
+  console.log(`       evolit ${terminal.cyan("<dev|build|start>")} [--port 3000]`);
 }
 
 async function createSite(projectRoot, targetDirectory) {
@@ -35,7 +36,7 @@ async function createSite(projectRoot, targetDirectory) {
   }
 
   const createdDirectory = await scaffoldSite(path.resolve(projectRoot, targetDirectory));
-  console.log(`Created evolit site: ${createdDirectory}`);
+  console.log(`${terminal.green("✓")} Created evolit site: ${terminal.cyan(createdDirectory)}`);
 }
 
 async function run() {
@@ -55,23 +56,25 @@ async function run() {
   if (command === "build") {
     const { buildProject } = await import("./build.js");
     const manifestPath = await buildProject(projectRoot);
-    console.log(`Built evolit app: ${path.relative(projectRoot, manifestPath)}`);
+    console.log(`${terminal.green("✓")} Built Evolit app: ${terminal.cyan(path.relative(projectRoot, manifestPath))}`);
     return;
   }
 
   if (command === "start") {
     const { createStartServer } = await import("./server.js");
+    console.log(`${terminal.cyan("▲")} ${terminal.bold("Evolit")} ${terminal.cyan("start")}`);
     const server = await createStartServer(projectRoot, options);
     await server.listen();
-    console.log(`evolit start listening on http://localhost:${server.port}`);
+    console.log(`${terminal.green("✓")} Ready on ${terminal.cyan(`http://localhost:${server.port}`)}`);
     return;
   }
 
   if (command === "dev") {
     const { createDevServer } = await import("./server.js");
+    console.log(`${terminal.cyan("▲")} ${terminal.bold("Evolit")} ${terminal.cyan("dev")}`);
     const server = await createDevServer(projectRoot, options);
     await server.listen();
-    console.log(`evolit dev listening on http://localhost:${server.port}`);
+    console.log(`${terminal.green("✓")} Ready on ${terminal.cyan(`http://localhost:${server.port}`)}`);
     return;
   }
 
@@ -79,6 +82,8 @@ async function run() {
 }
 
 run().catch((error) => {
-  console.error(error instanceof Error ? error.stack ?? error.message : String(error));
+  console.error(
+    `${terminal.red("[evolit]")} ${terminal.red("✖")} ${error instanceof Error ? error.stack ?? error.message : String(error)}`,
+  );
   process.exitCode = 1;
 });

package/src/client-assets.js

@@ -36,6 +36,23 @@ const sharedRuntimeBuildCache = new Map();
 const clientVendorSpecifierCache = new Map();
 const clientModuleMetadataCache = new Map();
 
+export function resetDevelopmentAssetCaches(projectRoot) {
+  const normalizedProjectRoot = path.resolve(projectRoot);
+  const developmentPrefix = `${normalizedProjectRoot}::development::`;
+
+  for (const cache of [
+    sharedRuntimeBuildCache,
+    clientVendorSpecifierCache,
+    clientModuleMetadataCache,
+  ]) {
+    for (const key of cache.keys()) {
+      if (key.startsWith(developmentPrefix)) {
+        cache.delete(key);
+      }
+    }
+  }
+}
+
 function isBareSpecifier(specifier) {
   return (
     typeof specifier === "string" &&

package/src/compiler.js

@@ -25,6 +25,7 @@ const developmentGraphCache = new Map();
 const developmentGraphDependencies = new Map();
 const developmentModuleNamespaceCache = new Map();
 const developmentGraphVersions = new Map();
+const developmentExternalImportWarnings = new Set();
 
 function isRelativeSpecifier(specifier) {
   return specifier.startsWith("./") || specifier.startsWith("../");
@@ -60,6 +61,29 @@ function isStyleAssetPath(filePath) {
   return filePath.endsWith(".css");
 }
 
+function isPathOutsideProject(projectRoot, filePath) {
+  const relativePath = path.relative(projectRoot, filePath);
+  return (
+    relativePath === ".." ||
+    relativePath.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relativePath)
+  );
+}
+
+function reportDevelopmentExternalImport(projectRoot, sourcePath, resolvedImportPath, onDevelopmentEvent) {
+  const warningKey = `${path.resolve(projectRoot)}::${sourcePath}::${resolvedImportPath}`;
+  if (developmentExternalImportWarnings.has(warningKey)) {
+    return;
+  }
+
+  developmentExternalImportWarnings.add(warningKey);
+  onDevelopmentEvent?.({
+    type: "external-import",
+    sourcePath,
+    resolvedImportPath,
+  });
+}
+
 function createStaticAssetStubSource(relativeAssetPath, mode, target = "server", staticAssetPublicUrls = null) {
   const normalizedAssetPath = relativeAssetPath.split(path.sep).join("/");
   if (normalizedAssetPath.endsWith(".css")) {
@@ -112,7 +136,7 @@ function getTypedOutputRoot(projectRoot, mode, target = "server") {
 }
 
 function toOutputPath(projectRoot, outputRoot, sourcePath) {
-  const relativePath = path.relative(projectRoot, sourcePath);
+  const relativePath = toOutputRelativePath(projectRoot, sourcePath);
   const extension = path.extname(relativePath);
   if (!extension) {
     return path.join(outputRoot, `${relativePath}.mjs`);
@@ -124,6 +148,22 @@ function toOutputPath(projectRoot, outputRoot, sourcePath) {
   );
 }
 
+function toOutputRelativePath(projectRoot, sourcePath) {
+  const relativePath = path.relative(projectRoot, sourcePath);
+  const isOutsideProject =
+    relativePath === ".." ||
+    relativePath.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relativePath);
+  if (!isOutsideProject) {
+    return relativePath;
+  }
+
+  return path.join(
+    "__external__",
+    ...relativePath.split(path.sep).map((segment) => segment === ".." ? "__up__" : segment),
+  );
+}
+
 async function rewriteRelativeSpecifiers({
   projectRoot,
   outputRoot,
@@ -138,6 +178,7 @@ async function rewriteRelativeSpecifiers({
   sourceMaps,
   outputPath,
   inputSourceMap,
+  onDevelopmentEvent,
 }) {
   const magicSource = new MagicString(code);
   let didRewrite = false;
@@ -169,13 +210,17 @@ async function rewriteRelativeSpecifiers({
       continue;
     }
 
+    if (mode === "development" && isPathOutsideProject(projectRoot, resolvedImportPath)) {
+      reportDevelopmentExternalImport(projectRoot, sourcePath, resolvedImportPath, onDevelopmentEvent);
+    }
+
     const importerOutputPath = toOutputPath(projectRoot, outputRoot, sourcePath);
     let compiledImportPath = null;
 
     if (shouldCompileModule(resolvedImportPath)) {
       compiledImportPath = await compileModule(resolvedImportPath);
     } else if (isStaticAssetPath(resolvedImportPath)) {
-      const relativeAssetPath = path.relative(projectRoot, resolvedImportPath);
+      const relativeAssetPath = toOutputRelativePath(projectRoot, resolvedImportPath);
       const assetOutputPath = path.join(outputRoot, relativeAssetPath);
       const stubOutputPath = `${assetOutputPath}.mjs`;
 
@@ -293,6 +338,14 @@ export function invalidateDevelopmentCompilationCache(projectRoot, changedPaths
     : null;
   let invalidated = false;
 
+  if (normalizedChangedPaths == null) {
+    for (const warningKey of developmentExternalImportWarnings) {
+      if (warningKey.startsWith(prefix)) {
+        developmentExternalImportWarnings.delete(warningKey);
+      }
+    }
+  }
+
   for (const key of developmentGraphCache.keys()) {
     if (!key.startsWith(prefix)) {
       continue;
@@ -323,6 +376,7 @@ async function compileModuleGraphUncached(entryPath, options = {}) {
     ssr = false,
     target = "server",
     staticAssetPublicUrls = null,
+    onDevelopmentEvent,
   } = options;
 
   const outputRoot = getTypedOutputRoot(projectRoot, mode, target);
@@ -361,6 +415,7 @@ async function compileModuleGraphUncached(entryPath, options = {}) {
       sourceMaps,
       outputPath,
       inputSourceMap: transformed.map ?? null,
+      onDevelopmentEvent,
     });
 
     await fs.writeFile(outputPath, rewritten.code, "utf8");

package/src/deployment-runtime.js

@@ -10,17 +10,20 @@ import {
   createAssetResolver,
   createHydrationBootstrap,
   createStaticAssetPublicUrlMap,
+  buildSharedVendorRuntime,
   emitBundledClientAssetsWithState,
   getAssetByPublicUrl,
   getSharedOutputRoot,
   normalizeHydrationDataForClient,
   normalizeClientAssetManifest,
+  resetDevelopmentAssetCaches,
   resolveRouteClientImports,
   resolveSharedVendorModuleUrl,
   resolveBrowserPackageAssetFilePath,
   rewriteHydrationDataScript,
 } from "./client-assets.js";
 import { loadEvolitConfig } from "./config.js";
+import { DEV_DIRECTORY, INTERNAL_DIRECTORY } from "./constants.js";
 import { createRouteResolver } from "./render.js";
 import {
   createCachedRouteResponse,
@@ -212,7 +215,14 @@ export function createResponseCacheController({ responseCacheRuntime }) {
   };
 }
 
-export async function createRequestRenderer({ projectRoot, mode, assetManifest, routeResolver, responseCacheRuntime }) {
+export async function createRequestRenderer({
+  projectRoot,
+  mode,
+  assetManifest,
+  routeResolver,
+  responseCacheRuntime,
+  onDevelopmentEvent,
+}) {
   let currentAssetManifest = normalizeClientAssetManifest(assetManifest);
   let currentAssetResolver = createAssetResolver(projectRoot, {
     assetManifest: currentAssetManifest,
@@ -241,11 +251,18 @@ export async function createRequestRenderer({ projectRoot, mode, assetManifest,
     return nextWork;
   }
 
+  function reportDevelopmentEvent(event) {
+    if (mode === "development" && typeof onDevelopmentEvent === "function") {
+      onDevelopmentEvent(event);
+    }
+  }
+
   function getDevClientModuleKey(clientModule) {
     return path.resolve(projectRoot, clientModule);
   }
   async function createFrameworkRouteResolver() {
     return createRouteResolver(projectRoot, mode, {
+      onDevelopmentEvent,
       getStaticAssetPublicUrls() {
         return createStaticAssetPublicUrlMap(currentAssetManifest);
       },
@@ -338,6 +355,12 @@ export async function createRequestRenderer({ projectRoot, mode, assetManifest,
           }
         }
 
+        reportDevelopmentEvent({
+          type: "invalidated",
+          changedPathCount: normalizedChangedPaths?.size ?? null,
+          affectedClientEntryCount: affectedClientModules.size,
+        });
+
         if (usesFrameworkRouteResolver) {
           effectiveRouteResolver = await createFrameworkRouteResolver();
         }
@@ -360,6 +383,7 @@ export async function createRequestRenderer({ projectRoot, mode, assetManifest,
             mode,
             sourceMaps: false,
             target: "client",
+            onDevelopmentEvent,
           });
         }
         return;
@@ -378,6 +402,7 @@ export async function createRequestRenderer({ projectRoot, mode, assetManifest,
             mode,
             sourceMaps: true,
             target: "client",
+            onDevelopmentEvent,
           });
           devPreparedClientModules.add(clientModuleKey);
           devClientModuleDependencies.set(
@@ -392,10 +417,16 @@ export async function createRequestRenderer({ projectRoot, mode, assetManifest,
 
         if (!discoveredClientEntry && currentAssetManifest) {
           developmentMetrics.clientArtifactCacheHits += 1;
+          reportDevelopmentEvent({ type: "client-assets-cache-hit" });
           return;
         }
 
         developmentMetrics.clientArtifactBuilds += 1;
+        const buildStartedAt = performance.now();
+        reportDevelopmentEvent({
+          type: "client-assets-building",
+          entryCount: devBundledEntries.size,
+        });
         const bundledClientAssets = await emitBundledClientAssetsWithState(projectRoot, {
           mode: "development",
           entryClientModules: devBundledEntries,
@@ -415,6 +446,11 @@ export async function createRequestRenderer({ projectRoot, mode, assetManifest,
           },
         ) ?? currentHydrationModuleUrl;
         devRollupCache = bundledClientAssets.rollupCache;
+        reportDevelopmentEvent({
+          type: "client-assets-ready",
+          durationMs: Math.round(performance.now() - buildStartedAt),
+          entryCount: devBundledEntries.size,
+        });
       });
     },
     async resolveRoutePolicy(request) {
@@ -453,7 +489,26 @@ export async function createDeploymentRuntime({
   assetManifest,
   responseCacheRuntime,
   routeResolver,
+  onDevelopmentEvent,
 } = {}) {
+  function reportDevelopmentEvent(event) {
+    if (mode === "development" && typeof onDevelopmentEvent === "function") {
+      onDevelopmentEvent(event);
+    }
+  }
+
+  if (mode === "development") {
+    reportDevelopmentEvent({ type: "initializing" });
+    const developmentRoot = path.join(projectRoot, INTERNAL_DIRECTORY, DEV_DIRECTORY);
+    await fs.rm(developmentRoot, { recursive: true, force: true });
+    invalidateDevelopmentCompilationCache(projectRoot);
+    resetDevelopmentAssetCaches(projectRoot);
+    await buildSharedVendorRuntime(projectRoot, "development", {
+      additionalEntrySpecifiers: [],
+    });
+    reportDevelopmentEvent({ type: "vendor-runtime-ready" });
+  }
+
   const effectiveResponseCacheRuntime = responseCacheRuntime
     ?? await resolveResponseCacheRuntime(
       projectRoot,
@@ -461,7 +516,7 @@ export async function createDeploymentRuntime({
       await loadEvolitConfig(projectRoot),
     );
   const runtimeState = {
-    assetManifest: normalizeClientAssetManifest(assetManifest),
+    assetManifest: mode === "development" ? null : normalizeClientAssetManifest(assetManifest),
   };
   const assets = createPublicAssetOrigin({
     projectRoot,
@@ -476,6 +531,7 @@ export async function createDeploymentRuntime({
     assetManifest: runtimeState.assetManifest,
     responseCacheRuntime: effectiveResponseCacheRuntime,
     routeResolver,
+    onDevelopmentEvent,
   });
 
   return {

package/src/render.js

@@ -12,6 +12,7 @@ import {
   isEvolitHttpSignal,
   runWithRequestContext,
 } from "./request-context.js";
+import { terminal } from "./terminal.js";
 import {
   LITSX_COMPONENT,
   LITSX_SERVER_COMPONENT,
@@ -89,7 +90,10 @@ function createBoundaryError(error, { mode, route, reportRouteError }) {
   if (typeof reportRouteError === "function") {
     reportRouteError(report);
   } else {
-    console.error(`[evolit] Route rendering failed (${digest}) at ${route.pathname}`, originalError);
+    console.error(
+      `${terminal.red("[evolit]")} ${terminal.red("✖")} Route rendering failed ${terminal.dim(`(${digest})`)} at ${terminal.cyan(route.pathname)}`,
+      originalError,
+    );
   }
 
   const boundaryError = new Error("An unexpected server error occurred.");
@@ -133,6 +137,7 @@ function createRouteModuleOptions(projectRoot, mode, options = {}) {
     mode,
     ssr: true,
     staticAssetPublicUrls: resolvedStaticAssetPublicUrls,
+    onDevelopmentEvent: options.onDevelopmentEvent,
   };
 }
 

package/src/server.js

@@ -9,6 +9,7 @@ import { APP_DIRECTORY, BUILD_DIRECTORY, INTERNAL_DIRECTORY, MANIFEST_FILENAME }
 import { normalizeClientAssetManifest } from "./client-assets.js";
 import { pathExists, readJson } from "./fs-utils.js";
 import { createDefaultRouteCacheKey, resolveResponseCacheRuntime } from "./response-cache.js";
+import { terminal } from "./terminal.js";
 
 function getPort(explicitPort) {
   const port = explicitPort ?? process.env.PORT ?? "3000";
@@ -139,6 +140,58 @@ async function createRecursiveDirectoryWatcher(rootDirectory, onChange) {
 }
 
 async function createServer(projectRoot, mode, explicitPort, options = {}) {
+  const reportDevelopmentEvent = mode === "development"
+    ? options.onDevelopmentEvent ?? ((event) => {
+      switch (event.type) {
+        case "initializing":
+          console.log(`${terminal.cyan("[evolit]")} ${terminal.yellow("○")} Preparing development runtime…`);
+          break;
+        case "vendor-runtime-ready":
+          console.log(`${terminal.cyan("[evolit]")} ${terminal.green("✓")} Vendor runtime ready.`);
+          break;
+        case "client-assets-building":
+          console.log(`${terminal.cyan("[evolit]")} ${terminal.magenta("○")} Compiling client assets (${event.entryCount} entries)…`);
+          break;
+        case "client-assets-ready":
+          console.log(`${terminal.cyan("[evolit]")} ${terminal.green("✓")} Client assets compiled in ${terminal.dim(`${event.durationMs}ms`)} (${event.entryCount} entries).`);
+          break;
+        case "client-assets-cache-hit":
+          console.log(`${terminal.cyan("[evolit]")} ${terminal.blue("●")} Client assets served from cache.`);
+          break;
+        case "invalidated":
+          console.log(
+            `${terminal.cyan("[evolit]")} ${terminal.yellow("△")} Source change detected${event.changedPathCount == null ? "" : ` (${event.changedPathCount} files)`}; invalidated ${event.affectedClientEntryCount} client entries.`,
+          );
+          break;
+        case "external-import":
+          console.warn(
+            `${terminal.yellow("[evolit]")} ${terminal.yellow("⚠")} Development import ${terminal.cyan(JSON.stringify(event.resolvedImportPath))} from ${terminal.cyan(JSON.stringify(event.sourcePath))} is outside the project root. It will be emitted under ${terminal.cyan("/_evolit/static/__external__/")}.`,
+          );
+          break;
+        case "request": {
+          const statusColor = event.status >= 500
+            ? terminal.red
+            : event.status >= 400
+              ? terminal.yellow
+              : event.status >= 300
+                ? terminal.blue
+                : terminal.green;
+          console.log(
+            `${terminal.cyan("[evolit]")} ${terminal.dim(event.method)} ${event.pathname} ${statusColor(event.status)} in ${terminal.dim(`${event.durationMs}ms`)}${event.cacheState ? ` ${terminal.blue(`(${event.cacheState})`)}` : ""}`,
+          );
+          break;
+        }
+        case "request-error":
+          console.error(
+            `${terminal.red("[evolit]")} ${terminal.red("✖")} ${event.method} ${event.pathname} failed`,
+            event.error,
+          );
+          break;
+        default:
+          break;
+      }
+    })
+    : null;
   const evolitConfig = options.evolitConfig ?? await loadEvolitConfig(projectRoot);
   const responseCacheRuntime = options.responseCacheStore
     ? {
@@ -151,6 +204,7 @@ async function createServer(projectRoot, mode, explicitPort, options = {}) {
     mode,
     assetManifest: normalizeClientAssetManifest(options.assetManifest),
     responseCacheRuntime,
+    onDevelopmentEvent: reportDevelopmentEvent,
   });
   const port = getPort(explicitPort);
   const liveReloadServer = mode === "development" ? new WebSocketServer({ noServer: true }) : null;
@@ -226,6 +280,7 @@ async function createServer(projectRoot, mode, explicitPort, options = {}) {
         headers: req.headers,
         ...(method === "GET" || method === "HEAD" ? {} : { body: req, duplex: "half" }),
       });
+      const requestStartedAt = performance.now();
       const response = await deploymentRuntime.handle(request);
       const servedResponse = mode === "development"
         ? injectLiveReloadSnippet(response)
@@ -233,7 +288,24 @@ async function createServer(projectRoot, mode, explicitPort, options = {}) {
 
       res.writeHead(servedResponse.status, servedResponse.headers);
       await writeResponseBody(res, servedResponse.body);
+      if (mode === "development" && !pathname.startsWith("/_evolit/")) {
+        const durationMs = Math.round(performance.now() - requestStartedAt);
+        reportDevelopmentEvent({
+          type: "request",
+          method,
+          pathname,
+          status: servedResponse.status,
+          durationMs,
+          cacheState: servedResponse.headers?.["x-evolit-cache"] ?? null,
+        });
+      }
     } catch (error) {
+      reportDevelopmentEvent?.({
+        type: "request-error",
+        method: req.method ?? "GET",
+        pathname: req.url ?? "/",
+        error,
+      });
       res.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
       res.end(error instanceof Error ? error.stack ?? error.message : String(error));
     }

package/src/terminal.js

@@ -0,0 +1,32 @@
+const enabled = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+
+function style(open, value) {
+  return enabled ? `\u001B[${open}m${value}\u001B[0m` : String(value);
+}
+
+export const terminal = {
+  bold(value) {
+    return style("1", value);
+  },
+  dim(value) {
+    return style("2", value);
+  },
+  red(value) {
+    return style("31", value);
+  },
+  green(value) {
+    return style("32", value);
+  },
+  yellow(value) {
+    return style("33", value);
+  },
+  blue(value) {
+    return style("34", value);
+  },
+  magenta(value) {
+    return style("35", value);
+  },
+  cyan(value) {
+    return style("36", value);
+  },
+};