@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/src/plugins/cloudflare-wasm.ts

@@ -0,0 +1,141 @@
+/**
+ * timber-cloudflare-wasm — Handle WASM modules for Cloudflare Workers builds.
+ *
+ * Cloudflare Workers can natively import `.wasm` files as compiled
+ * WebAssembly.Module. But Rolldown can't load `.wasm` files at build time.
+ *
+ * This plugin bridges the gap:
+ * 1. Adds the `workerd` resolve condition so libraries like @takumi-rs/wasm
+ *    resolve to their Cloudflare-native entry (bare `.wasm` import)
+ * 2. Externalizes `.wasm` imports so Rolldown skips them
+ * 3. Copies the WASM files to the build output so wrangler can find them
+ *
+ * Only active for Cloudflare adapter production builds — every hook bails
+ * unless `isCloudflareBuild` was set in configResolved. In dev and non-CF
+ * builds, `.wasm` imports are left to Vite's own handling (?init / ?url or
+ * a clear build error), never silently externalized.
+ */
+
+import { basename, resolve, dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+import { copyFile, mkdir, readFile } from 'node:fs/promises';
+import type { Plugin, ResolvedConfig } from 'vite';
+import type { PluginContext } from '../plugin-context.ts';
+
+function isCloudflareAdapter(ctx: PluginContext): boolean {
+  const adapter = ctx.config.adapter as { name?: string } | undefined;
+  return adapter?.name === 'cloudflare';
+}
+
+export function timberCloudflareWasm(ctx: PluginContext): Plugin[] {
+  // Resolved WASM files, keyed by absolute source path so two files that
+  // share a basename (e.g. lib_bg.wasm from two packages) don't collide.
+  // The value is the unique output basename used for the external import
+  // specifier and the copy destination.
+  const wasmFiles = new Map<string, string>();
+  const usedBasenames = new Set<string>();
+  let isCloudflareBuild = false;
+
+  const plugin: Plugin = {
+    name: 'timber-cloudflare-wasm',
+
+    configResolved(resolved: ResolvedConfig) {
+      if (resolved.command !== 'build') return;
+      if (!isCloudflareAdapter(ctx)) return;
+      isCloudflareBuild = true;
+
+      // Prepend `workerd` to resolve conditions for server environments
+      // so @takumi-rs/wasm/auto resolves to the Cloudflare-native entry
+      // (bare WASM import) instead of the Vite entry (?url + fetch).
+      // Must happen in configResolved because the RSC plugin sets its own
+      // conditions during config — merging via config() would lose them.
+      for (const envName of ['rsc', 'ssr']) {
+        const env = resolved.environments[envName];
+        if (!env) continue;
+        const conditions = env.resolve.conditions;
+        if (!conditions.includes('workerd')) {
+          conditions.unshift('workerd');
+        }
+      }
+    },
+
+    // Strip /* @vite-ignore */ from @takumi-rs/wasm dynamic imports so
+    // Rolldown bundles them instead of leaving bare specifiers that fail
+    // at runtime on Cloudflare Workers (no node_modules).
+    transform(code, id) {
+      if (!isCloudflareBuild) return;
+      if (!id.includes('takumi')) return;
+      const stripped = code.replaceAll(
+        /\/\*\s*@vite-ignore\s*\*\/\s*\n\s*"@takumi-rs\/wasm"/g,
+        '"@takumi-rs/wasm"'
+      );
+      if (stripped !== code) return stripped;
+    },
+
+    resolveId: {
+      order: 'pre',
+      async handler(source, importer) {
+        if (!isCloudflareBuild) return;
+        if (!source.endsWith('.wasm')) return;
+
+        let absolutePath: string;
+        if (source.startsWith('.') && importer) {
+          absolutePath = resolve(dirname(importer), source);
+        } else {
+          return;
+        }
+
+        let outputName = wasmFiles.get(absolutePath);
+        if (!outputName) {
+          outputName = basename(absolutePath);
+          if (usedBasenames.has(outputName)) {
+            // Another wasm file already claimed this basename — disambiguate
+            // with a short content hash so both files land in the output.
+            const hash = createHash('sha256')
+              .update(await readFile(absolutePath))
+              .digest('hex')
+              .slice(0, 8);
+            outputName = outputName.replace(/\.wasm$/, `.${hash}.wasm`);
+          }
+          usedBasenames.add(outputName);
+          wasmFiles.set(absolutePath, outputName);
+        }
+
+        return { id: './' + outputName, external: true };
+      },
+    },
+
+    async writeBundle(options, bundle) {
+      if (!isCloudflareBuild) return;
+      if (wasmFiles.size === 0) return;
+
+      const outDir = options.dir;
+      if (!outDir) return;
+
+      // Find which output chunks reference WASM files and copy the WASM
+      // to the same directory so the relative imports resolve correctly.
+      const targetDirs = new Set<string>();
+      for (const chunk of Object.values(bundle)) {
+        if (chunk.type !== 'chunk') continue;
+        for (const outputName of wasmFiles.values()) {
+          if (chunk.code.includes(outputName)) {
+            targetDirs.add(dirname(resolve(outDir, chunk.fileName)));
+          }
+        }
+      }
+
+      if (targetDirs.size === 0) return;
+
+      const copies: Promise<void>[] = [];
+      for (const dir of targetDirs) {
+        await mkdir(dir, { recursive: true });
+        for (const [absolutePath, outputName] of wasmFiles) {
+          copies.push(copyFile(absolutePath, resolve(dir, outputName)));
+        }
+      }
+      await Promise.all(copies);
+    },
+  };
+
+  return [plugin];
+}

package/src/plugins/content.ts

@@ -8,10 +8,10 @@
  * Design doc: 20-content-collections.md §"Content Collections"
  */
 
-import type { Plugin } from 'vite';
+import type { Plugin, PluginOption } from 'vite';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import type { PluginContext } from '#/index.js';
+import type { PluginContext } from '../plugin-context.ts';
 
 const CONFIG_FILE_NAMES = [
   'content-collections.ts',
@@ -31,6 +31,27 @@ function findConfigFile(root: string): string | undefined {
   return undefined;
 }
 
+/** The name @content-collections/vite gives its plugin. */
+const CONTENT_COLLECTIONS_PLUGIN_NAME = 'content-collections';
+
+/**
+ * Whether the user's own config already registers @content-collections/vite.
+ * Walks nested arrays and awaits promised plugins, the same PluginOption
+ * shapes Vite flattens (and has already resolved by the time config hooks
+ * run, so awaiting here costs nothing).
+ */
+async function registersContentCollections(plugins: PluginOption[] | undefined): Promise<boolean> {
+  for (const option of plugins ?? []) {
+    const plugin = await option;
+    if (Array.isArray(plugin)) {
+      if (await registersContentCollections(plugin)) return true;
+    } else if (plugin && 'name' in plugin && plugin.name === CONTENT_COLLECTIONS_PLUGIN_NAME) {
+      return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Create the timber-content Vite plugin.
  *
@@ -75,6 +96,10 @@ export function timberContent(ctx: PluginContext): Plugin {
     name: 'timber-content',
 
     async config(config, env) {
+      // Two registrations start two builders and two watchers that race on
+      // the same cache ("Failed to parse the cache mapping"). The user's
+      // own registration, with its options, wins.
+      if (await registersContentCollections(config.plugins)) return;
       const root = config.root ?? ctx.root;
       ctx.timer.start('content-activate');
       await activate(root);
@@ -127,6 +152,10 @@ export function timberContent(ctx: PluginContext): Plugin {
     },
 
     async configureServer(server) {
+      // The analyze crawl child must not start content-collections'
+      // file watcher — it outlives server.close() and holds the
+      // process open (the child relies on process.exit to clean up).
+      if (process.env.TIMBER_ANALYZE === '1') return;
       if (!innerPlugin) return;
       if (typeof innerPlugin.configureServer === 'function') {
         await (innerPlugin.configureServer as (...args: unknown[]) => unknown).call(this, server);

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.
+    }
+  });
+}