@qzsy/vinext 0.1.7

package/dist/utils/project.js

@@ -0,0 +1,213 @@
+import fs from "node:fs";
+import path from "node:path";
+//#region src/utils/project.ts
+/**
+* Shared project utilities — used by both `vinext init` and `vinext deploy`.
+*
+* These functions detect and modify project configuration without touching
+* any Next.js source files, config files, or tsconfig.json.
+*/
+/** Common CJS config files that may need renaming when adding "type": "module" */
+const CJS_CONFIG_FILES = [
+	"postcss.config.js",
+	"tailwind.config.js",
+	".eslintrc.js",
+	"prettier.config.js",
+	"stylelint.config.js",
+	"commitlint.config.js",
+	"jest.config.js",
+	"babel.config.js",
+	".babelrc.js"
+];
+/**
+* Ensure package.json has "type": "module".
+* Returns true if it was added (i.e. it wasn't already there).
+*/
+function ensureESModule(root) {
+	const pkgPath = path.join(root, "package.json");
+	if (!fs.existsSync(pkgPath)) return false;
+	try {
+		const raw = fs.readFileSync(pkgPath, "utf-8");
+		const pkg = JSON.parse(raw);
+		if (pkg.type === "module") return false;
+		pkg.type = "module";
+		fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf-8");
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Rename CJS config files (that use `module.exports`) to .cjs
+* to avoid breakage when "type": "module" is added.
+* Returns array of [oldName, newName] pairs that were renamed.
+*/
+function renameCJSConfigs(root) {
+	const renamed = [];
+	for (const fileName of CJS_CONFIG_FILES) {
+		const filePath = path.join(root, fileName);
+		if (!fs.existsSync(filePath)) continue;
+		try {
+			const content = fs.readFileSync(filePath, "utf-8");
+			if (/\bmodule\.exports\b/.test(content) || /\brequire\s*\(/.test(content)) {
+				const newName = fileName.replace(/\.js$/, ".cjs");
+				const newPath = path.join(root, newName);
+				fs.renameSync(filePath, newPath);
+				renamed.push([fileName, newName]);
+			}
+		} catch {}
+	}
+	return renamed;
+}
+/**
+* Ensure the project is configured for ESM before Vite loads vite.config.ts.
+*
+* This mirrors what `vinext init` does, but is applied lazily at dev/build
+* time for projects that were set up before `vinext init` added the step.
+*
+* Side effects: may rename `.js` CJS config files to `.cjs` and add
+* `"type": "module"` to package.json.
+*
+* @returns Object describing what was changed, or null if nothing was done.
+*/
+function ensureViteConfigCompatibility(root) {
+	if (!hasViteConfig(root)) return null;
+	const pkgPath = path.join(root, "package.json");
+	if (!fs.existsSync(pkgPath)) return null;
+	let pkg;
+	try {
+		pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+	} catch {
+		return null;
+	}
+	if (pkg.type === "module") return null;
+	if (pkg.type !== void 0) return null;
+	const renamed = renameCJSConfigs(root);
+	let addedTypeModule = false;
+	try {
+		pkg.type = "module";
+		fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf-8");
+		addedTypeModule = true;
+	} catch {}
+	return {
+		renamed,
+		addedTypeModule
+	};
+}
+/**
+* Walk from `start` up to the filesystem root, calling `check` on each
+* directory. Returns the first non-null value returned by `check`, or null.
+*
+* This is the shared primitive used by both lock-file detection and
+* node_modules resolution to support monorepo layouts where the relevant
+* files live at the workspace root rather than inside each app package.
+*/
+function walkUpUntil(start, check) {
+	let dir = path.resolve(start);
+	const { root: fsRoot } = path.parse(dir);
+	while (true) {
+		const result = check(dir);
+		if (result !== null) return result;
+		if (dir === fsRoot) return null;
+		dir = path.dirname(dir);
+	}
+}
+function parsePackageManagerName(value) {
+	if (!value) return null;
+	const fromPkg = value.trim().toLowerCase().split("@")[0];
+	if (fromPkg === "pnpm" || fromPkg === "yarn" || fromPkg === "bun" || fromPkg === "npm") return fromPkg;
+	const fromUA = value.trim().toLowerCase().split(" ")[0]?.split("/")[0];
+	if (fromUA === "pnpm" || fromUA === "yarn" || fromUA === "bun" || fromUA === "npm") return fromUA;
+	return null;
+}
+function detectPackageManagerFromPackageJson(root) {
+	const pkgPath = path.join(root, "package.json");
+	if (!fs.existsSync(pkgPath)) return null;
+	try {
+		return parsePackageManagerName(JSON.parse(fs.readFileSync(pkgPath, "utf-8")).packageManager);
+	} catch {
+		return null;
+	}
+}
+/**
+* Check a single directory for lock files, returning the package manager name.
+* Used by walkUpUntil to walk ancestor directories in monorepos.
+*/
+function checkLockFiles(dir) {
+	if (fs.existsSync(path.join(dir, "pnpm-lock.yaml"))) return "pnpm";
+	if (fs.existsSync(path.join(dir, "yarn.lock"))) return "yarn";
+	if (fs.existsSync(path.join(dir, "bun.lock")) || fs.existsSync(path.join(dir, "bun.lockb"))) return "bun";
+	if (fs.existsSync(path.join(dir, "package-lock.json")) || fs.existsSync(path.join(dir, "npm-shrinkwrap.json"))) return "npm";
+	return null;
+}
+/**
+* Detect which package manager name is used.
+* Priority:
+* 1) lock files (walks up parent directories for monorepo support)
+* 2) package.json#packageManager
+* 3) invoking CLI user agent (npm_config_user_agent)
+* 4) npm fallback
+*/
+function detectPackageManagerName(root, env = process.env) {
+	const fromLockFile = walkUpUntil(root, checkLockFiles);
+	if (fromLockFile) return fromLockFile;
+	const fromPkg = detectPackageManagerFromPackageJson(root);
+	if (fromPkg) return fromPkg;
+	const fromUA = parsePackageManagerName(env.npm_config_user_agent);
+	if (fromUA) return fromUA;
+	return "npm";
+}
+/**
+* Detect which package manager install command to use.
+* Returns the dev-install command string (e.g. "pnpm add -D").
+*/
+function detectPackageManager(root) {
+	const pm = detectPackageManagerName(root);
+	if (pm === "npm") return "npm install -D";
+	return `${pm} add -D`;
+}
+/**
+* Walk from `start` up to the filesystem root looking for a path inside
+* node_modules. Returns the first absolute path found, or null.
+*
+* Handles monorepos where packages are hoisted to the workspace root's
+* node_modules rather than installed in each app's own node_modules.
+*
+* @param start   - Directory to begin the search (usually the project root)
+* @param subPath - Path relative to a node_modules dir, e.g. ".bin/wrangler"
+*                  or "@cloudflare/vite-plugin"
+*/
+function findInNodeModules(start, subPath) {
+	return walkUpUntil(start, (dir) => {
+		const candidate = path.join(dir, "node_modules", subPath);
+		return fs.existsSync(candidate) ? candidate : null;
+	});
+}
+/**
+* Check if a vite.config file exists in the project root.
+*/
+function hasViteConfig(root) {
+	return fs.existsSync(path.join(root, "vite.config.ts")) || fs.existsSync(path.join(root, "vite.config.js")) || fs.existsSync(path.join(root, "vite.config.mjs"));
+}
+/**
+* Return the first candidate directory (resolved against `root`) that exists,
+* or null. Used to locate conventional `app`/`pages` directories that may live
+* at the root or under `src/`.
+*/
+function findDir(root, ...candidates) {
+	for (const candidate of candidates) {
+		const full = path.join(root, candidate);
+		try {
+			if (fs.statSync(full).isDirectory()) return full;
+		} catch {}
+	}
+	return null;
+}
+/**
+* Check if the project uses App Router (has an app/ directory).
+*/
+function hasAppDir(root) {
+	return findDir(root, "app", path.join("src", "app")) !== null;
+}
+//#endregion
+export { detectPackageManager, detectPackageManagerName, ensureESModule, ensureViteConfigCompatibility, findDir, findInNodeModules, hasAppDir, hasViteConfig, renameCJSConfigs };

package/dist/utils/promise.d.ts

@@ -0,0 +1,4 @@
+//#region src/utils/promise.d.ts
+declare function isPromiseLike(value: unknown): value is PromiseLike<unknown>;
+//#endregion
+export { isPromiseLike };

package/dist/utils/promise.js

@@ -0,0 +1,6 @@
+//#region src/utils/promise.ts
+function isPromiseLike(value) {
+	return Boolean(value && (typeof value === "object" || typeof value === "function") && "then" in value && typeof value.then === "function");
+}
+//#endregion
+export { isPromiseLike };

package/dist/utils/public-routes.d.ts

@@ -0,0 +1,4 @@
+//#region src/utils/public-routes.d.ts
+declare function scanPublicFileRoutes(root: string): string[];
+//#endregion
+export { scanPublicFileRoutes };

package/dist/utils/public-routes.js

@@ -0,0 +1,48 @@
+import fs from "node:fs";
+import path from "node:path";
+//#region src/utils/public-routes.ts
+function scanPublicFileRoutes(root) {
+	const publicDir = path.join(root, "public");
+	const routes = [];
+	const visitedDirs = /* @__PURE__ */ new Set();
+	function walk(dir) {
+		let realDir;
+		try {
+			realDir = fs.realpathSync(dir);
+		} catch {
+			return;
+		}
+		if (visitedDirs.has(realDir)) return;
+		visitedDirs.add(realDir);
+		const entries = fs.readdirSync(dir, { withFileTypes: true });
+		for (const entry of entries) {
+			const fullPath = path.join(dir, entry.name);
+			if (entry.isDirectory()) {
+				walk(fullPath);
+				continue;
+			}
+			if (entry.isSymbolicLink()) {
+				let stat;
+				try {
+					stat = fs.statSync(fullPath);
+				} catch {
+					continue;
+				}
+				if (stat.isDirectory()) {
+					walk(fullPath);
+					continue;
+				}
+				if (!stat.isFile()) continue;
+			} else if (!entry.isFile()) continue;
+			const relativePath = path.relative(publicDir, fullPath).split(path.sep).join("/");
+			routes.push("/" + relativePath);
+		}
+	}
+	if (fs.existsSync(publicDir)) try {
+		walk(publicDir);
+	} catch {}
+	routes.sort();
+	return routes;
+}
+//#endregion
+export { scanPublicFileRoutes };

package/dist/utils/query.d.ts

@@ -0,0 +1,49 @@
+//#region src/utils/query.d.ts
+/**
+ * Add a query parameter value to an object, promoting to array for duplicate keys.
+ * Matches Next.js behavior: ?a=1&a=2 → { a: ['1', '2'] }
+ */
+type UrlQueryValue = string | number | boolean | null | undefined;
+type UrlQuery = Record<string, UrlQueryValue | readonly UrlQueryValue[]>;
+declare function addQueryParam(obj: Record<string, string | string[]>, key: string, value: string): void;
+/**
+ * Merge pathname-derived dynamic route params into a query object.
+ *
+ * Route params must win over same-name URL search params so `/posts/123?id=456`
+ * still exposes `id: "123"` to Pages Router APIs.
+ */
+declare function mergeRouteParamsIntoQuery(query: Record<string, string | string[]>, params: Record<string, string | string[]>): Record<string, string | string[]>;
+/**
+ * Parse a URL's query string into a Record, with multi-value keys promoted to arrays.
+ *
+ * Per RFC 3986 only the first `?` separates path from query; any further `?`
+ * characters are part of the query string itself (e.g. `/linker?href=/about?hello=world`
+ * has the query `href=/about?hello=world`). Using `indexOf("?")` instead of
+ * `split("?")[1]` preserves the rest of the query so values like `<Link href>`
+ * targets keep their own query strings intact.
+ */
+declare function parseQueryString(url: string): Record<string, string | string[]>;
+declare function urlQueryToSearchParams(query: UrlQuery): URLSearchParams;
+/**
+ * Merge the original request URL's query parameters into a rewrite-target URL.
+ *
+ * Matches Next.js behavior: original query params are preserved on rewrites,
+ * but the rewrite-target URL wins on key conflicts. Ported from Next.js
+ * `Object.assign(parsedUrl.query, rewrittenParsedUrl.query)` in
+ * route-modules/route-module.ts.
+ *
+ * https://github.com/vercel/next.js/blob/canary/packages/next/src/server/route-modules/route-module.ts
+ *
+ * The fragment from `rewriteUrl` is preserved (origin/pathname always come
+ * from the rewrite target). Absolute rewrite URLs are returned unchanged when
+ * the origin differs from the original — external rewrites are proxied
+ * elsewhere and shouldn't have local query params smuggled in.
+ */
+declare function mergeRewriteQuery(originalUrl: string, rewriteUrl: string): string;
+/**
+ * Append query parameters to a URL while preserving any existing query string
+ * and fragment identifier.
+ */
+declare function appendSearchParamsToUrl(url: string, params: Iterable<[string, string]>): string;
+//#endregion
+export { UrlQuery, addQueryParam, appendSearchParamsToUrl, mergeRewriteQuery, mergeRouteParamsIntoQuery, parseQueryString, urlQueryToSearchParams };

package/dist/utils/query.js

@@ -0,0 +1,122 @@
+//#region src/utils/query.ts
+function setOwnQueryValue(obj, key, value) {
+	Object.defineProperty(obj, key, {
+		value,
+		enumerable: true,
+		writable: true,
+		configurable: true
+	});
+}
+function addQueryParam(obj, key, value) {
+	if (Object.hasOwn(obj, key)) {
+		const current = obj[key];
+		setOwnQueryValue(obj, key, Array.isArray(current) ? current.concat(value) : [current, value]);
+	} else setOwnQueryValue(obj, key, value);
+}
+/**
+* Merge pathname-derived dynamic route params into a query object.
+*
+* Route params must win over same-name URL search params so `/posts/123?id=456`
+* still exposes `id: "123"` to Pages Router APIs.
+*/
+function mergeRouteParamsIntoQuery(query, params) {
+	const merged = { ...query };
+	for (const [key, value] of Object.entries(params)) setOwnQueryValue(merged, key, Array.isArray(value) ? [...value] : value);
+	return merged;
+}
+/**
+* Parse a URL's query string into a Record, with multi-value keys promoted to arrays.
+*
+* Per RFC 3986 only the first `?` separates path from query; any further `?`
+* characters are part of the query string itself (e.g. `/linker?href=/about?hello=world`
+* has the query `href=/about?hello=world`). Using `indexOf("?")` instead of
+* `split("?")[1]` preserves the rest of the query so values like `<Link href>`
+* targets keep their own query strings intact.
+*/
+function parseQueryString(url) {
+	const queryIndex = url.indexOf("?");
+	if (queryIndex === -1) return {};
+	const hashIndex = url.indexOf("#", queryIndex + 1);
+	const qs = hashIndex === -1 ? url.slice(queryIndex + 1) : url.slice(queryIndex + 1, hashIndex);
+	if (!qs) return {};
+	const params = new URLSearchParams(qs);
+	const query = {};
+	for (const [key, value] of params) addQueryParam(query, key, value);
+	return query;
+}
+/**
+* Convert a Next.js-style query object into URLSearchParams while preserving
+* repeated keys for array values.
+*
+* Ported from Next.js `urlQueryToSearchParams()`:
+* https://github.com/vercel/next.js/blob/canary/packages/next/src/shared/lib/router/utils/querystring.ts
+*/
+function stringifyUrlQueryParam(param) {
+	if (typeof param === "string") return param;
+	if (typeof param === "number" && !isNaN(param) || typeof param === "boolean") return String(param);
+	return "";
+}
+function urlQueryToSearchParams(query) {
+	const params = new URLSearchParams();
+	for (const [key, value] of Object.entries(query)) {
+		if (Array.isArray(value)) {
+			for (const item of value) params.append(key, stringifyUrlQueryParam(item));
+			continue;
+		}
+		params.set(key, stringifyUrlQueryParam(value));
+	}
+	return params;
+}
+/**
+* Merge the original request URL's query parameters into a rewrite-target URL.
+*
+* Matches Next.js behavior: original query params are preserved on rewrites,
+* but the rewrite-target URL wins on key conflicts. Ported from Next.js
+* `Object.assign(parsedUrl.query, rewrittenParsedUrl.query)` in
+* route-modules/route-module.ts.
+*
+* https://github.com/vercel/next.js/blob/canary/packages/next/src/server/route-modules/route-module.ts
+*
+* The fragment from `rewriteUrl` is preserved (origin/pathname always come
+* from the rewrite target). Absolute rewrite URLs are returned unchanged when
+* the origin differs from the original — external rewrites are proxied
+* elsewhere and shouldn't have local query params smuggled in.
+*/
+function mergeRewriteQuery(originalUrl, rewriteUrl) {
+	const originalSearchIndex = originalUrl.indexOf("?");
+	if (originalSearchIndex === -1) return rewriteUrl;
+	const originalQuery = originalUrl.slice(originalSearchIndex + 1).split("#")[0];
+	if (!originalQuery) return rewriteUrl;
+	const hashIndex = rewriteUrl.indexOf("#");
+	const beforeHash = hashIndex === -1 ? rewriteUrl : rewriteUrl.slice(0, hashIndex);
+	const hash = hashIndex === -1 ? "" : rewriteUrl.slice(hashIndex);
+	const queryIndex = beforeHash.indexOf("?");
+	const base = queryIndex === -1 ? beforeHash : beforeHash.slice(0, queryIndex);
+	const rewriteQuery = queryIndex === -1 ? "" : beforeHash.slice(queryIndex + 1);
+	const merged = new URLSearchParams(originalQuery);
+	const rewriteParams = new URLSearchParams(rewriteQuery);
+	const rewriteKeys = /* @__PURE__ */ new Set();
+	for (const key of rewriteParams.keys()) rewriteKeys.add(key);
+	for (const key of rewriteKeys) merged.delete(key);
+	for (const [key, value] of rewriteParams) merged.append(key, value);
+	const search = merged.toString();
+	return `${base}${search ? `?${search}` : ""}${hash}`;
+}
+/**
+* Append query parameters to a URL while preserving any existing query string
+* and fragment identifier.
+*/
+function appendSearchParamsToUrl(url, params) {
+	const hashIndex = url.indexOf("#");
+	const beforeHash = hashIndex === -1 ? url : url.slice(0, hashIndex);
+	const hash = hashIndex === -1 ? "" : url.slice(hashIndex);
+	const queryIndex = beforeHash.indexOf("?");
+	const base = queryIndex === -1 ? beforeHash : beforeHash.slice(0, queryIndex);
+	const existingQuery = queryIndex === -1 ? "" : beforeHash.slice(queryIndex + 1);
+	const merged = new URLSearchParams(existingQuery);
+	for (const [key, value] of params) merged.append(key, value);
+	const search = merged.toString();
+	return `${base}${search ? `?${search}` : ""}${hash}`;
+}
+//#endregion
+export { addQueryParam, appendSearchParamsToUrl, mergeRewriteQuery, mergeRouteParamsIntoQuery, parseQueryString, urlQueryToSearchParams };

package/dist/utils/record.d.ts

@@ -0,0 +1,4 @@
+//#region src/utils/record.d.ts
+declare function isUnknownRecord(value: unknown): value is Record<string, unknown>;
+//#endregion
+export { isUnknownRecord };

package/dist/utils/record.js

@@ -0,0 +1,6 @@
+//#region src/utils/record.ts
+function isUnknownRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+//#endregion
+export { isUnknownRecord };

package/dist/utils/regex.d.ts

@@ -0,0 +1,4 @@
+//#region src/utils/regex.d.ts
+declare function escapeRegExp(value: string): string;
+//#endregion
+export { escapeRegExp };

package/dist/utils/regex.js

@@ -0,0 +1,6 @@
+//#region src/utils/regex.ts
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//#endregion
+export { escapeRegExp };

package/dist/utils/safe-json-file.d.ts

@@ -0,0 +1,17 @@
+//#region src/utils/safe-json-file.d.ts
+/**
+ * Read and parse a JSON file, returning `null` if the file is missing,
+ * unreadable, or contains invalid JSON.
+ *
+ * Pass `onError` to log/observe failures while still receiving `null`. The
+ * callback is invoked for any thrown error from `readFileSync` or
+ * `JSON.parse` (e.g. `ENOENT`, syntax errors).
+ *
+ * Callers that need a default value other than `null` should map the result:
+ *   `readJsonFile<string[]>(p) ?? []`
+ */
+declare function readJsonFile<T>(filePath: string, options?: {
+  onError?: (err: unknown) => void;
+}): T | null;
+//#endregion
+export { readJsonFile };

package/dist/utils/safe-json-file.js

@@ -0,0 +1,23 @@
+import fs from "node:fs";
+//#region src/utils/safe-json-file.ts
+/**
+* Read and parse a JSON file, returning `null` if the file is missing,
+* unreadable, or contains invalid JSON.
+*
+* Pass `onError` to log/observe failures while still receiving `null`. The
+* callback is invoked for any thrown error from `readFileSync` or
+* `JSON.parse` (e.g. `ENOENT`, syntax errors).
+*
+* Callers that need a default value other than `null` should map the result:
+*   `readJsonFile<string[]>(p) ?? []`
+*/
+function readJsonFile(filePath, options) {
+	try {
+		return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+	} catch (err) {
+		options?.onError?.(err);
+		return null;
+	}
+}
+//#endregion
+export { readJsonFile };

package/dist/utils/sorted-array.d.ts

@@ -0,0 +1,8 @@
+//#region src/utils/sorted-array.d.ts
+type SortedStringPosition = Readonly<{
+  found: boolean;
+  index: number;
+}>;
+declare function findSortedStringPosition(values: readonly string[], candidate: string): SortedStringPosition;
+//#endregion
+export { findSortedStringPosition };

package/dist/utils/sorted-array.js

@@ -0,0 +1,20 @@
+//#region src/utils/sorted-array.ts
+function findSortedStringPosition(values, candidate) {
+	let lower = 0;
+	let upper = values.length;
+	while (lower < upper) {
+		const middle = lower + Math.floor((upper - lower) / 2);
+		if (values[middle] === candidate) return {
+			found: true,
+			index: middle
+		};
+		if (values[middle] < candidate) lower = middle + 1;
+		else upper = middle;
+	}
+	return {
+		found: false,
+		index: lower
+	};
+}
+//#endregion
+export { findSortedStringPosition };

package/dist/utils/text-stream.d.ts

@@ -0,0 +1,28 @@
+//#region src/utils/text-stream.d.ts
+/**
+ * Helpers for the repeated `new TextDecoder()` + `ReadableStream` chunk-loop
+ * pattern used across the server. Each helper handles the streaming-decode
+ * boundary correctly (final empty `decoder.decode()` flush so any incomplete
+ * trailing UTF-8 sequence is reported).
+ *
+ * Sites with additional load-bearing behaviour (line-buffered transforms,
+ * raw-byte accumulators, mixed string/Uint8Array streams, cache-key body
+ * canonicalisation) intentionally still inline their own decoder.
+ */
+/**
+ * Drain a UTF-8 byte stream and return the full decoded text. The stream
+ * reader is released on both success and failure.
+ */
+declare function readStreamAsText(stream: ReadableStream<Uint8Array>): Promise<string>;
+/**
+ * Drain a UTF-8 byte stream up to `maxBytes` of *raw* input, returning the
+ * decoded text. If the raw size limit is exceeded, cancellation is signalled
+ * and `onLimitExceeded` is invoked; it MUST throw — its return type is
+ * `never` to enforce that. Each caller passes its own error type.
+ *
+ * The size check is on raw bytes (pre-decode) to bound memory before
+ * paying the decoder cost.
+ */
+declare function readStreamAsTextWithLimit(stream: ReadableStream<Uint8Array>, maxBytes: number, onLimitExceeded: () => never): Promise<string>;
+//#endregion
+export { readStreamAsText, readStreamAsTextWithLimit };

package/dist/utils/text-stream.js

@@ -0,0 +1,64 @@
+//#region src/utils/text-stream.ts
+/**
+* Helpers for the repeated `new TextDecoder()` + `ReadableStream` chunk-loop
+* pattern used across the server. Each helper handles the streaming-decode
+* boundary correctly (final empty `decoder.decode()` flush so any incomplete
+* trailing UTF-8 sequence is reported).
+*
+* Sites with additional load-bearing behaviour (line-buffered transforms,
+* raw-byte accumulators, mixed string/Uint8Array streams, cache-key body
+* canonicalisation) intentionally still inline their own decoder.
+*/
+/**
+* Drain a UTF-8 byte stream and return the full decoded text. The stream
+* reader is released on both success and failure.
+*/
+async function readStreamAsText(stream) {
+	const reader = stream.getReader();
+	const decoder = new TextDecoder();
+	const chunks = [];
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			chunks.push(decoder.decode(value, { stream: true }));
+		}
+		chunks.push(decoder.decode());
+		return chunks.join("");
+	} finally {
+		reader.releaseLock();
+	}
+}
+/**
+* Drain a UTF-8 byte stream up to `maxBytes` of *raw* input, returning the
+* decoded text. If the raw size limit is exceeded, cancellation is signalled
+* and `onLimitExceeded` is invoked; it MUST throw — its return type is
+* `never` to enforce that. Each caller passes its own error type.
+*
+* The size check is on raw bytes (pre-decode) to bound memory before
+* paying the decoder cost.
+*/
+async function readStreamAsTextWithLimit(stream, maxBytes, onLimitExceeded) {
+	const reader = stream.getReader();
+	const decoder = new TextDecoder();
+	const chunks = [];
+	let totalSize = 0;
+	try {
+		for (;;) {
+			const result = await reader.read();
+			if (result.done) break;
+			totalSize += result.value.byteLength;
+			if (totalSize > maxBytes) {
+				reader.cancel();
+				onLimitExceeded();
+			}
+			chunks.push(decoder.decode(result.value, { stream: true }));
+		}
+		chunks.push(decoder.decode());
+		return chunks.join("");
+	} finally {
+		reader.releaseLock();
+	}
+}
+//#endregion
+export { readStreamAsText, readStreamAsTextWithLimit };

package/dist/utils/vinext-root.d.ts

@@ -0,0 +1,23 @@
+//#region src/utils/vinext-root.d.ts
+/**
+ * Resolve the root directory of the vinext package at runtime.
+ *
+ * Both the CLI pre-flight check (`cli.ts`) and the standalone output emitter
+ * (`build/standalone.ts`) need to locate vinext's package root so they can
+ * verify that `dist/` exists and copy vinext's runtime files into standalone
+ * output.  Centralising the logic here ensures the two callers stay in sync.
+ *
+ * The resolution works for both the compiled output layout and for running
+ * directly from source:
+ *
+ *   - Compiled layout:  this file lives at `dist/utils/vinext-root.js`
+ *                       → two levels up (`../..`) is the package root.
+ *   - Source layout:    this file lives at `src/utils/vinext-root.ts`
+ *                       → two levels up (`../..`) is the package root.
+ *
+ * If an explicit root is provided (e.g. from a test fixture), it is returned
+ * as-is after resolving to an absolute path.
+ */
+declare function resolveVinextPackageRoot(explicitRoot?: string): string;
+//#endregion
+export { resolveVinextPackageRoot };