@timber-js/app 0.2.0-alpha.191 → 0.2.0-alpha.194

package/src/plugins/dev-discovery.ts

@@ -0,0 +1,218 @@
+/**
+ * Dev-server discovery records — `.timber/dev/<pid>-<port>-<token>.json`.
+ *
+ * On startup each dev server writes `{ port, pid, host, protocol }` to its own record
+ * file under the app's `.timber/dev/` so the `timber graph` CLI and the
+ * VS Code extension can discover a running dev server for the
+ * live-graph fast path.
+ *
+ * One record file per server, one writer per file. This is what makes
+ * multi-server roots (Vite auto-increments the port across processes;
+ * programmatic embeddings run several servers in one process) safe
+ * without any coordination: there is no shared file to displace, no
+ * ownership to arbitrate, and no shutdown-order dependency — each
+ * server removes exactly its own record.
+ *
+ * Consumers must list the directory and trust a record only if its pid
+ * is alive AND a probe request to the endpoint succeeds; anything else
+ * is treated as absent (silent fallback), never an error. Stale records
+ * (crashed servers) are therefore the normal case — startup sweeps
+ * dead-pid records best-effort, and consumers validate the rest away.
+ *
+ * The directory layout and file format are implementation details, not
+ * a public contract.
+ *
+ * Design doc: 47-module-environment-tooling.md §5, 21-dev-server.md.
+ */
+
+import type { Server } from 'node:net';
+import { Server as TlsServer } from 'node:tls';
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, writeFileSync, rmSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Relative path of the discovery directory within the project root. */
+export const DEV_DISCOVERY_DIR = join('.timber', 'dev');
+
+export interface DevRecord {
+  port: number;
+  pid: number;
+  /**
+   * The bound address, as reported by the socket. Consumers probing the
+   * endpoint need it for servers bound to non-default interfaces;
+   * wildcard addresses (`0.0.0.0`, `::`) should be probed via loopback.
+   */
+  host: string;
+  /**
+   * Probe scheme. `server.https` dev servers (including HTTP/2) answer
+   * only TLS — an http:// probe of one would fail and wrongly trigger
+   * the cold-crawl fallback.
+   */
+  protocol: 'http' | 'https';
+  /**
+   * Vite `base` path. When non-root (e.g. `/my-app/`), the WebSocket
+   * upgrade path is `base + hmrPath`.
+   */
+  base?: string;
+  /**
+   * HMR WebSocket path (from `server.ws.path` or deprecated
+   * `server.hmr.path`). Absent when no path is configured (default `/`).
+   */
+  hmrPath?: string;
+  /**
+   * Custom WebSocket host override (from `server.ws.host` or deprecated
+   * `server.hmr.host`). When set, the WS connection targets this host
+   * instead of the HTTP server's bound address.
+   */
+  hmrHost?: string;
+  /**
+   * Custom WebSocket port override (from `server.ws.clientPort` ??
+   * `server.ws.port`, or deprecated `server.hmr.clientPort` ??
+   * `server.hmr.port`). When set, the WS connection targets this port
+   * instead of the HTTP server's bound port.
+   */
+  hmrPort?: number;
+  /**
+   * Custom WebSocket protocol override (from `server.ws.protocol` or
+   * deprecated `server.hmr.protocol`). When set (e.g. `'wss'`), the
+   * upgrade request uses the corresponding HTTP scheme.
+   */
+  hmrProtocol?: string;
+  /**
+   * Vite 8 WebSocket token (from `config.webSocketToken`). Required for
+   * browser WS upgrades; the extension passes it as `?token=` on the
+   * WebSocket URL.
+   */
+  webSocketToken?: string;
+  /**
+   * Absolute path to the Vite config file this server was started with.
+   * When multiple dev servers share a project root but use different
+   * configs, the fast path must only accept the record matching the
+   * config the CLI resolved (TIM-1393).
+   */
+  configFile?: string;
+}
+
+/** Best-effort "is this pid alive" — signal 0 probes without killing. */
+export function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM means the process exists but is owned by someone else.
+    return (error as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+/**
+ * Remove sibling records whose pid is no longer alive. Purely a
+ * tidiness sweep — consumers already ignore records that fail the
+ * pid + probe validation, so missing a stale record here is harmless.
+ */
+function sweepDeadRecords(dir: string): void {
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.endsWith('.json')) continue;
+    const filePath = join(dir, entry);
+    try {
+      const record = JSON.parse(readFileSync(filePath, 'utf8')) as Partial<DevRecord>;
+      // Remove only records that parse AND name a dead pid. An
+      // unreadable file may be a sibling's record mid-write — leave it;
+      // consumers ignore records that fail validation anyway.
+      if (typeof record.pid === 'number' && !isPidAlive(record.pid)) {
+        rmSync(filePath, { force: true });
+      }
+    } catch {
+      // Unreadable — skip, never delete another writer's in-flight file.
+    }
+  }
+}
+
+/**
+ * Register discovery-record lifecycle handlers on the dev server's HTTP
+ * server. Writes `.timber/dev/<pid>-<port>-<token>.json` once the server is
+ * listening (the bound port is only known then) and removes exactly
+ * that record on clean shutdown.
+ *
+ * All filesystem work is best-effort: a failure to write or remove a
+ * record must never break the dev server. `httpServer` is null in
+ * middleware mode — no port exists, so there is nothing to advertise.
+ * Typed as `net.Server` — the common base of Vite's `http.Server` and
+ * `Http2SecureServer` variants, which carries the events and `address()`.
+ */
+export function registerDevDiscovery(
+  httpServer: Server | null,
+  root: string,
+  config?: {
+    configFile?: string | false;
+    base?: string;
+    server?: {
+      hmr?:
+        | { path?: string; host?: string; port?: number; clientPort?: number; protocol?: string }
+        | boolean;
+      ws?:
+        | { path?: string; host?: string; port?: number; clientPort?: number; protocol?: string }
+        | false;
+    };
+    webSocketToken?: string;
+  }
+): void {
+  if (!httpServer) return;
+
+  const dir = join(root, DEV_DISCOVERY_DIR);
+  let recordPath: string | null = null;
+
+  httpServer.on('listening', () => {
+    const address = httpServer.address();
+    // Unix-socket listeners have a string address — no port to advertise.
+    if (address === null || typeof address === 'string') return;
+    const hmrOpts = typeof config?.server?.hmr === 'object' ? config.server.hmr : undefined;
+    const wsOpts = typeof config?.server?.ws === 'object' ? config.server.ws : undefined;
+    const record: DevRecord = {
+      port: address.port,
+      pid: process.pid,
+      host: address.address,
+      // Vite's https/h2 servers are tls.Server subclasses; plain HTTP
+      // and h2c are not.
+      protocol: httpServer instanceof TlsServer ? 'https' : 'http',
+      base: config?.base && config.base !== '/' ? config.base : undefined,
+      hmrPath: wsOpts?.path ?? hmrOpts?.path,
+      hmrHost: wsOpts?.host ?? hmrOpts?.host,
+      hmrPort:
+        wsOpts?.clientPort || wsOpts?.port || hmrOpts?.clientPort || hmrOpts?.port || undefined,
+      hmrProtocol: wsOpts?.protocol ?? hmrOpts?.protocol,
+      webSocketToken: config?.webSocketToken,
+      configFile: typeof config?.configFile === 'string' ? config.configFile : undefined,
+    };
+    // pid+port alone is not a unique server identity (same port on two
+    // interfaces; worker threads and duplicate module copies share a
+    // pid but not module state, so a counter cannot disambiguate
+    // either). A random token makes the filename unique regardless of
+    // process/isolate topology; pid and port stay in the name only for
+    // human debuggability.
+    recordPath = join(dir, `${record.pid}-${record.port}-${randomUUID()}.json`);
+    try {
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(recordPath, JSON.stringify(record));
+      sweepDeadRecords(dir);
+    } catch {
+      // Best-effort — consumers fall back to the cold crawl.
+    }
+  });
+
+  httpServer.on('close', () => {
+    if (!recordPath) return;
+    try {
+      // Only ever this server's own record — sibling servers' records
+      // are separate files and survive any shutdown order untouched.
+      rmSync(recordPath, { force: true });
+    } catch {
+      // Best-effort — a stale record is validated away by consumers.
+    }
+  });
+}

package/src/plugins/dev-server.ts

@@ -15,25 +15,31 @@
 import type { Plugin, ViteDevServer, DevEnvironment } from 'vite';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { TLSSocket } from 'node:tls';
-import { existsSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
 import { sendNodeResponse } from 'srvx/node';
-import type { PluginContext } from '../plugin-context.js';
+import type { PluginContext } from '../plugin-context.ts';
 import {
   sendErrorToOverlay,
   classifyErrorPhase,
   fixErrorStacktrace,
   parseFirstAppFrame,
   type ErrorPhase,
-} from '../dev-tools/overlay.js';
-import { generateDevErrorPage } from '../dev-tools/error-page.js';
-import { extractHmrOptions, type DevErrorHmrOptions } from '../dev-tools/dev-page-shell.js';
-import { addVirtualModuleContext } from '../config-validation.js';
-import { compressResponse } from '../server/compress.js';
-import { isMetadataRouteServePath } from '../server/metadata-routes.js';
-import { canonicalize } from '../server/canonicalize.js';
-import { matchUrlParts } from '../server/tree-match.js';
-import type { RouteTree } from '../routing/types.js';
+} from '../dev-tools/overlay.ts';
+import { generateDevErrorPage } from '../dev-tools/error-page.ts';
+import { extractHmrOptions, type DevErrorHmrOptions } from '../dev-tools/dev-page-shell.ts';
+import { addVirtualModuleContext } from '../config-validation.ts';
+import { registerDevDiscovery } from './dev-discovery.ts';
+import {
+  createGraphEndpointMiddleware,
+  makeGraphUpdateChannel,
+  type GraphUpdateChannel,
+} from './graph-endpoint.ts';
+import { compressResponse } from '../server/compress.ts';
+import { isMetadataRouteServePath } from '../server/metadata-routes.ts';
+import { canonicalize } from '../server/canonicalize.ts';
+import { matchUrlParts } from '../server/tree-match.ts';
+import type { RouteTree } from '../routing/types.ts';
 
 // ─── Constants ────────────────────────────────────────────────────────────
 
@@ -70,6 +76,10 @@ const ASSET_EXTENSIONS =
  * Hook: configureServer (returns post-hook to register after Vite's middleware)
  */
 export function timberDevServer(ctx: PluginContext): Plugin {
+  // Set in configureServer, consumed by hotUpdate/transform — the
+  // graph push channel emits through the server's HMR transport.
+  let graphChannel: GraphUpdateChannel | null = null;
+
   return {
     name: 'timber-dev-server',
 
@@ -77,6 +87,28 @@ export function timberDevServer(ctx: PluginContext): Plugin {
     // See 21-dev-server.md §Plugin Registration.
     apply: 'serve',
 
+    /**
+     * Push channel for the graph endpoint, phase 1: `invalidated`, one
+     * per (file, environment). Emitted from hotUpdate — which runs
+     * AFTER Vite invalidates the environment module graphs — never
+     * from a raw watcher listener, which would race consumers into
+     * querying pre-invalidation memberships (design/47 §"Dev-server
+     * endpoint").
+     */
+    hotUpdate({ file, type }) {
+      graphChannel?.onHotUpdate({ file, type, environment: this.environment.name });
+    },
+
+    /**
+     * Push channel phase 2: `transformed`, when a pending-invalidated
+     * module's import edges are actually rebuilt. A Set lookup for
+     * everything without a pending invalidation — free on the hot
+     * path. Returning nothing leaves the code untouched.
+     */
+    transform(_code, id) {
+      graphChannel?.onTransform(id, this.environment.name);
+    },
+
     /**
      * Register the dev server middleware and config file watcher.
      *
@@ -103,9 +135,62 @@ export function timberDevServer(ctx: PluginContext): Plugin {
       // as Vite's '{ type: "error" }' payload to trigger the overlay.
       listenForClientErrors(server, ctx.root);
 
+      // GET /__timber/graph — module-environment classification from the
+      // live env graphs, plus the timber:graph-update HMR push channel.
+      // Registered before the timber middleware so /__timber/* requests
+      // never reach the app pipeline. Dev-only by construction (this
+      // plugin is apply: 'serve'). See design/47 §"Dev-server endpoint".
+      server.middlewares.use(createGraphEndpointMiddleware(server, ctx));
+      graphChannel = makeGraphUpdateChannel(
+        ctx,
+        (payload) => server.hot.send(payload),
+        // "Edges rebuilt" signal: Vite sets a node's transformResult at
+        // the END of the transform request, after vite:import-analysis
+        // has updated the importer edges. Virtual ids (the route
+        // manifest's structural updates) have no file index — resolve
+        // them by id.
+        (file, environment) => {
+          const graph = server.environments[environment]?.moduleGraph;
+          if (!graph) return false;
+          const nodes = graph.getModulesByFile(file);
+          if (nodes) {
+            for (const node of nodes) {
+              if (node.transformResult != null) return true;
+            }
+            return false;
+          }
+          return graph.getModuleById(file)?.transformResult != null;
+        },
+        // Canonicalize watcher/hook paths into the module graphs' path
+        // space: under the default preserveSymlinks:false the graphs
+        // carry realpaths while watcher events can carry symlink paths
+        // — unkeyed by one canonical form, a pending entry would never
+        // match its own transform. Deleted files realpath their parent
+        // directory instead; virtual ids pass through untouched.
+        (file) => {
+          // Optional-chained: mock servers in unit tests carry a bare
+          // config object without resolve options.
+          if (server.config?.resolve?.preserveSymlinks || file.includes('virtual:')) return file;
+          try {
+            return realpathSync(file);
+          } catch {
+            try {
+              return join(realpathSync(dirname(file)), basename(file));
+            } catch {
+              return file;
+            }
+          }
+        }
+      );
+
       // Pre-hook — registers middleware before Vite's internals
       server.middlewares.use(createTimberMiddleware(server, ctx));
 
+      // Write this server's .timber/dev/<pid>-<port>-<token>.json record once
+      // the server is listening so the graph CLI / VS Code extension can
+      // discover it. See design/47-module-environment-tooling.md §5.
+      registerDevDiscovery(server.httpServer, ctx.root, server.config);
+
       // Wrap server.listen() to close the holding server immediately
       // before Vite binds the port — no gap where nothing is listening.
       // The holding server was started in rootSync's config() hook to

package/src/plugins/entries.ts

@@ -15,7 +15,7 @@ import type { Plugin } from 'vite';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { existsSync } from 'node:fs';
-import type { PluginContext } from '../plugin-context.js';
+import type { PluginContext } from '../plugin-context.ts';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 

package/src/plugins/fonts.ts

@@ -20,17 +20,17 @@
 
 import { parseAst } from 'vite';
 import type { Plugin, ResolvedConfig, ViteDevServer } from 'vite';
-import type { PluginContext } from '../plugin-context.js';
+import type { PluginContext } from '../plugin-context.ts';
 import {
   downloadAndCacheFonts,
   generateProductionFontFaces,
   resolveDevFontFaces,
-} from '../fonts/google.js';
-import { fontUrlPrefix } from '../fonts/paths.js';
-import { FontPipeline } from '../fonts/pipeline.js';
-import { runFontsTransform } from '../fonts/transform.js';
-import { installFontDevMiddleware } from '../fonts/dev-middleware.js';
-import { emitFontAssets, writeFontManifest, groupCachedFontsByFamily } from '../fonts/bundle.js';
+} from '../fonts/google.ts';
+import { fontUrlPrefix } from '../fonts/paths.ts';
+import { FontPipeline } from '../fonts/pipeline.ts';
+import { runFontsTransform } from '../fonts/transform.ts';
+import { installFontDevMiddleware } from '../fonts/dev-middleware.ts';
+import { emitFontAssets, writeFontManifest, groupCachedFontsByFamily } from '../fonts/bundle.ts';
 import {
   RESOLVED_GOOGLE,
   RESOLVED_LOCAL,
@@ -38,7 +38,7 @@ import {
   VIRTUAL_LOCAL,
   generateGoogleVirtualModule,
   generateLocalVirtualModule,
-} from '../fonts/virtual-modules.js';
+} from '../fonts/virtual-modules.ts';
 
 // ── Public re-exports ────────────────────────────────────────────────────
 //
@@ -47,7 +47,7 @@ import {
 // updating every caller. New helpers should be added to the per-concern
 // module first and re-exported here only if external code needs them.
 
-export { FontPipeline } from '../fonts/pipeline.js';
+export { FontPipeline } from '../fonts/pipeline.ts';
 export {
   generateFontId,
   extractFontConfig,
@@ -55,7 +55,7 @@ export {
   parseGoogleFontImports,
   parseGoogleFontFamilies,
   parseLocalFontImportName,
-} from '../fonts/transform.js';
+} from '../fonts/transform.ts';
 
 /**
  * Create the timber-fonts Vite plugin.
@@ -171,6 +171,13 @@ export function timberFonts(ctx: PluginContext): Plugin {
           return '';
         }
 
+        // The analyze crawl only needs import edges, not actual font
+        // CSS. Return an empty stylesheet so transforms resolve
+        // without triggering network fetches or cache writes.
+        if (process.env.TIMBER_ANALYZE === '1') {
+          return '';
+        }
+
         const skipFonts = process.env.TIMBER_SKIP_FONTS === '1';
 
         for (const font of pipeline.googleFonts()) {