@pantoken/vite-workspace-orchestrator 0.1.0

package/README.md

@@ -0,0 +1,51 @@
+# @pantoken/vite-workspace-orchestrator
+
+A Vite dev-server plugin that watches upstream workspace packages and rebuilds them (and their
+dependents) when source changes.
+
+When an app depends on local workspace packages, changes to those packages normally need a manual
+rebuild before the dev server reflects them. This plugin automates that: it watches each upstream
+package's source, rebuilds in topological order, and registers the built output with Vite's watcher
+so the browser reloads. It applies during `serve` only — production builds are untouched.
+
+Key behaviors:
+
+- Watches with native `fs.watch`, not Vite's chokidar, so paths outside the project root aren't
+  filtered out.
+- Debounces rapid changes per package before spawning a build.
+- Rebuilds dependents in topological order after a successful build.
+- Registers optional HMR paths with Vite's watcher, and mounts optional static file servers.
+
+## Usage
+
+```ts
+import { resolve } from "node:path";
+import { workspaceOrchestrator } from "@pantoken/vite-workspace-orchestrator";
+
+export default {
+  plugins: [
+    workspaceOrchestrator({
+      upstream: [
+        {
+          name: "@pantoken/components",
+          dir: resolve(root, "formats/components"),
+          watchPaths: [resolve(root, "formats/components/src")],
+          build: ["pnpm", "exec", "vp", "run", "@pantoken/components#build"],
+          dependents: [],
+        },
+      ],
+      hmrWatchPaths: [resolve(root, "formats/components/generated")],
+      debounceMs: 200,
+    }),
+  ],
+};
+```
+
+pantoken's docs site wires it in `docs/.vitepress/config.ts` so edits to `@pantoken/css` and
+`@pantoken/components` rebuild live during `docs:dev` instead of only at the next full build.
+
+## API
+
+- **`workspaceOrchestrator(options)`** — returns a Vite plugin (`apply: "serve"`).
+- **`matchesFilters(filename, node)`** — the include/ignore predicate, exported for testing.
+- **`OrchestratorOptions`**, **`UpstreamNode`**, **`FileServerEntry`** — the option types.

package/dist/index.d.mts

@@ -0,0 +1,105 @@
+import { ViteDevServer } from "vite";
+
+//#region src/types.d.ts
+/**
+ * Types for {@link workspaceOrchestrator}.
+ *
+ * @module
+ */
+/** One upstream workspace package to watch and rebuild. */
+interface UpstreamNode {
+  /** Display name for log messages. */
+  name: string;
+  /** Package root directory (the cwd for the build command). */
+  dir: string;
+  /** Paths (files or directories) to watch — directories are watched recursively. */
+  watchPaths: string[];
+  /** Build command: first element is the executable, the rest are arguments. */
+  build: readonly [string, ...string[]];
+  /** Names of other upstream nodes to rebuild after this one succeeds. */
+  dependents: readonly string[];
+  /**
+   * Glob patterns for files to include. When set, only changes to files matching at least one
+   * pattern trigger a rebuild. Omit to include everything.
+   */
+  include?: readonly string[];
+  /**
+   * Glob patterns for files to ignore. Changes to matching files are silently skipped. Omit to
+   * ignore nothing.
+   */
+  ignore?: readonly string[];
+}
+/** One static file-serving middleware entry. */
+interface FileServerEntry {
+  /** URL path prefix to mount the middleware at, e.g. `"/styles/apps"`. */
+  mountPath: string;
+  /** Local directory to serve files from. */
+  serveDir: string;
+  /** Only serve files whose URL path ends with this extension, e.g. `".css"`. */
+  extension: string;
+  /** Value for the `Content-Type` response header. */
+  contentType: string;
+  /**
+   * Optional transform applied to the URL-relative path before resolving against `serveDir`, e.g.
+   * `(p) => p.replace(/\/([^/]+)\.css$/, "/$1/app.css")`.
+   */
+  pathTransform?: (urlRelativePath: string) => string;
+}
+/** Options for {@link workspaceOrchestrator}. */
+interface OrchestratorOptions {
+  /** The upstream workspace dependency graph. */
+  upstream: readonly UpstreamNode[];
+  /**
+   * Paths to add to Vite's `server.watcher` so HMR fires when built output is updated (e.g. a
+   * package's `dist` or `generated` directory).
+   */
+  hmrWatchPaths?: readonly string[];
+  /**
+   * Paths to watch with native `fs.watch` for triggering module invalidation. Unlike
+   * `hmrWatchPaths` (which relies on chokidar), these are monitored with Node's native `fs.watch` —
+   * which reliably detects changes for pnpm-symlinked workspace `dist` directories. On a change, a
+   * synthetic `"change"` event is emitted on `server.watcher` so the module graph is invalidated.
+   */
+  reloadWatchPaths?: readonly string[];
+  /** Debounce delay in milliseconds before triggering a rebuild (default: 200). */
+  debounceMs?: number;
+  /** Optional static file-serving middleware entries. */
+  fileServers?: readonly FileServerEntry[];
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * Returns `true` if the changed filename passes the node's include/ignore filters.
+ *
+ * @example
+ * ```ts
+ * import { matchesFilters } from "@pantoken/vite-workspace-orchestrator";
+ *
+ * const node = {
+ *   name: "@pantoken/components",
+ *   dir: "/repo/formats/components",
+ *   watchPaths: ["/repo/formats/components/src"],
+ *   build: ["pnpm", "run", "build"] as const,
+ *   dependents: [],
+ *   include: ["**\/*.ts"],
+ *   ignore: ["**\/*.test.ts"],
+ * };
+ *
+ * matchesFilters("src/index.ts", node); // true
+ * matchesFilters("src/index.test.ts", node); // false (ignored)
+ * ```
+ */
+declare function matchesFilters(filename: string, node: UpstreamNode): boolean;
+/**
+ * Create the Vite dev-server plugin.
+ *
+ * @param options - {@link OrchestratorOptions}.
+ * @returns A Vite plugin object (`apply: "serve"`).
+ */
+declare const workspaceOrchestrator: (options: OrchestratorOptions) => {
+  apply: "serve";
+  name: string;
+  configureServer(server: ViteDevServer): void;
+};
+//#endregion
+export { type FileServerEntry, type OrchestratorOptions, type UpstreamNode, matchesFilters, workspaceOrchestrator };

package/dist/index.mjs

@@ -0,0 +1,202 @@
+import { readFileSync, watch } from "node:fs";
+import { matchesGlob, resolve } from "node:path";
+import { spawn } from "node:child_process";
+//#region src/file-server.ts
+/**
+* Static file-serving middleware for {@link workspaceOrchestrator}.
+*
+* @module
+*/
+/**
+* Register static file-serving middleware for each entry. Only files whose URL ends with the
+* configured extension are served; everything else falls through to the next handler.
+*
+* @param fileServers - The entries to mount.
+* @param middlewares - The connect-style middleware stack (e.g. `server.middlewares`).
+*/
+function mountFileServers(fileServers, middlewares) {
+	for (const entry of fileServers) middlewares.use(entry.mountPath, (req, res, next) => {
+		const filePath = req.url?.split("?")[0];
+		if (!filePath?.endsWith(entry.extension)) {
+			next();
+			return;
+		}
+		const resolved = entry.pathTransform ? entry.pathTransform(filePath) : filePath;
+		const fullPath = resolve(entry.serveDir, resolved.slice(1));
+		try {
+			const content = readFileSync(fullPath, "utf8");
+			res.setHeader("Content-Type", entry.contentType);
+			res.end(content);
+		} catch {
+			next();
+		}
+	});
+}
+//#endregion
+//#region src/scheduler.ts
+/**
+* A debounced, dependency-aware build scheduler for {@link workspaceOrchestrator}.
+*
+* @module
+*/
+const SUCCESS_EXIT_CODE = 0;
+/**
+* Create a debounced build scheduler for the given upstream node map. The returned function
+* debounces file-change events before spawning a build, re-queues a pending build if one is already
+* running, and rebuilds dependents in topological order on success.
+*
+* @param nodeMap - Upstream nodes keyed by name.
+* @param logger - The Vite logger (or any `info`/`error` sink).
+* @param debounceMs - Debounce delay before a build starts.
+* @returns A `scheduleRebuild(name)` function.
+*/
+function createScheduler(nodeMap, logger, debounceMs) {
+	const stateMap = new Map([...nodeMap.keys()].map((name) => [name, {
+		building: false,
+		pending: false,
+		debounce: null
+	}]));
+	const scheduler = {
+		scheduleRebuild(name) {
+			const s = stateMap.get(name);
+			if (!s) return;
+			if (s.debounce) clearTimeout(s.debounce);
+			s.debounce = setTimeout(() => {
+				s.debounce = null;
+				scheduler.runBuild(name);
+			}, debounceMs);
+		},
+		runBuild(name) {
+			const node = nodeMap.get(name);
+			const s = stateMap.get(name);
+			if (!node || !s) return;
+			if (s.building) {
+				s.pending = true;
+				return;
+			}
+			s.building = true;
+			logger.info(`\n[orchestrator] ${name} — building…`, { timestamp: true });
+			const [cmd, ...args] = node.build;
+			spawn(cmd, args, {
+				cwd: node.dir,
+				stdio: "inherit"
+			}).on("close", (code) => {
+				s.building = false;
+				if (code === SUCCESS_EXIT_CODE) {
+					logger.info(`[orchestrator] ${name} — done.`, { timestamp: true });
+					for (const dep of node.dependents) scheduler.scheduleRebuild(dep);
+				} else logger.error(`[orchestrator] ${name} — build failed (exit ${String(code)}).`, { timestamp: true });
+				if (s.pending) {
+					s.pending = false;
+					scheduler.runBuild(name);
+				}
+			});
+		}
+	};
+	return (name) => scheduler.scheduleRebuild(name);
+}
+//#endregion
+//#region src/index.ts
+/**
+* `@pantoken/vite-workspace-orchestrator` — a Vite dev-server plugin that watches upstream workspace
+* packages and rebuilds them (and their dependents) when source changes.
+*
+* During development, changes to a local workspace package normally need a manual rebuild before the
+* dev server reflects them. This plugin automates that: it watches each upstream package's source
+* with native `fs.watch` (not Vite's chokidar, which filters paths outside the project root),
+* debounces rapid changes, rebuilds in topological order, and registers built output with Vite's
+* watcher so the browser reloads. In pantoken's docs it keeps the generated CSS (`@pantoken/css`,
+* `@pantoken/components`) fresh as you edit the libraries, instead of only at build time.
+*
+* It applies during `serve` only, so production builds are untouched.
+*
+* @example
+* ```ts
+* import { resolve } from "node:path";
+* import { workspaceOrchestrator } from "@pantoken/vite-workspace-orchestrator";
+*
+* workspaceOrchestrator({
+*   upstream: [
+*     {
+*       name: "@pantoken/components",
+*       dir: resolve(root, "formats/components"),
+*       watchPaths: [resolve(root, "formats/components/src")],
+*       build: ["pnpm", "run", "build"],
+*       dependents: [],
+*     },
+*   ],
+*   hmrWatchPaths: [resolve(root, "formats/components/generated")],
+* });
+* ```
+*
+* @module
+* @experimental
+*/
+const DEFAULT_DEBOUNCE_MS = 200;
+/**
+* Returns `true` if the changed filename passes the node's include/ignore filters.
+*
+* @example
+* ```ts
+* import { matchesFilters } from "@pantoken/vite-workspace-orchestrator";
+*
+* const node = {
+*   name: "@pantoken/components",
+*   dir: "/repo/formats/components",
+*   watchPaths: ["/repo/formats/components/src"],
+*   build: ["pnpm", "run", "build"] as const,
+*   dependents: [],
+*   include: ["**\/*.ts"],
+*   ignore: ["**\/*.test.ts"],
+* };
+*
+* matchesFilters("src/index.ts", node); // true
+* matchesFilters("src/index.test.ts", node); // false (ignored)
+* ```
+*/
+function matchesFilters(filename, node) {
+	if (node.ignore?.some((pattern) => matchesGlob(filename, pattern))) return false;
+	if (node.include && !node.include.some((pattern) => matchesGlob(filename, pattern))) return false;
+	return true;
+}
+/**
+* Create the Vite dev-server plugin.
+*
+* @param options - {@link OrchestratorOptions}.
+* @returns A Vite plugin object (`apply: "serve"`).
+*/
+const workspaceOrchestrator = (options) => {
+	const { upstream, hmrWatchPaths = [], reloadWatchPaths = [], debounceMs = DEFAULT_DEBOUNCE_MS, fileServers = [] } = options;
+	return {
+		apply: "serve",
+		name: "workspace-orchestrator",
+		configureServer(server) {
+			const { logger } = server.config;
+			const scheduleRebuild = createScheduler(new Map(upstream.map((n) => [n.name, n])), logger, debounceMs);
+			const fsWatchers = [];
+			for (const node of upstream) for (const watchPath of node.watchPaths) try {
+				const watcher = watch(watchPath, { recursive: true }, (_event, filename) => {
+					if (filename !== null && !matchesFilters(filename, node)) return;
+					scheduleRebuild(node.name);
+				});
+				fsWatchers.push(watcher);
+			} catch {}
+			for (const hmrPath of hmrWatchPaths) server.watcher.add(hmrPath);
+			for (const reloadPath of reloadWatchPaths) try {
+				const watcher = watch(reloadPath, { recursive: true }, (_event, filename) => {
+					if (filename === null) return;
+					const fullPath = resolve(reloadPath, filename);
+					logger.info(`[orchestrator] invalidating ${fullPath}`, { timestamp: true });
+					server.watcher.emit("change", fullPath);
+				});
+				fsWatchers.push(watcher);
+			} catch {}
+			mountFileServers(fileServers, server.middlewares);
+			server.httpServer?.on("close", () => {
+				for (const w of fsWatchers) w.close();
+			});
+		}
+	};
+};
+//#endregion
+export { matchesFilters, workspaceOrchestrator };

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@pantoken/vite-workspace-orchestrator",
+  "version": "0.1.0",
+  "description": "Vite dev-server plugin that watches upstream workspace packages and rebuilds them (and their dependents) when source changes.",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "typescript": "^6.0.3",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.4",
+    "vite-plus": "0.2.4"
+  },
+  "peerDependencies": {
+    "vite": ">=6"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check"
+  }
+}