@orkestrel/scaffold 0.0.28 → 0.0.30

package/dist/src/core/index.cjs

@@ -290,7 +290,7 @@ var DEFAULT_ENGINES = `>=${MINIMUM_NODE_VERSION}`;
 var BASE_DEV_DEPENDENCIES = Object.freeze({
 	"@microsoft/api-extractor": "^7.58.12",
 	"@orkestrel/guide": "^0.0.10",
-	"@orkestrel/scaffold": "^0.0.28",
+	"@orkestrel/scaffold": "^0.0.30",
 	"@types/node": "^26.2.0",
 	oxfmt: "^0.62.0",
 	oxlint: "^1.77.0",
@@ -386,11 +386,11 @@ var CONFIG_TEMPLATES = Object.freeze({
 		vite: `import type { {{viteTypes}} } from 'vite'
 {{imports}}import { defineConfig, mergeConfig } from 'vitest/config'
 import tsconfig from './tsconfig.json' with { type: 'json' }
-{{helpers}}import { lstatSync, readdirSync, realpathSync } from 'node:fs'
+{{helpers}}{{browsers}}import { lstatSync, readdirSync, realpathSync } from 'node:fs'
 import { basename, join, parse, relative, resolve as resolvePath, sep } from 'node:path'
 import { fileURLToPath, URL } from 'node:url'
 
-export function resolveWorkspacePath(relativePath: string): string {
+{{options}}export function resolveWorkspacePath(relativePath: string): string {
 	return fileURLToPath(new URL(relativePath, import.meta.url))
 }
 
@@ -482,9 +482,10 @@ const resolve = {
 				name: { label: 'src:browser', color: 'yellow' },
 				include: ['tests/src/browser/**/*.test.ts'],
 {{exclude}}				setupFiles: ['./tests/setup.ts', './tests/setupBrowser.ts'],
+{{global}}
 				browser: {
 					enabled: true,
-					provider: playwright(),
+					provider: playwright(browserOptions),
 					instances: [{ browser: 'chromium', headless: true }],
 				},
 				fileParallelism: false,
@@ -595,7 +596,7 @@ const resolve = {
 			setupFiles: ['./tests/setup.ts', './tests/setupBrowser.ts'],
 			browser: {
 				enabled: true,
-				provider: playwright(),
+				provider: playwright(browserOptions),
 				instances: [{ browser: 'chromium', headless: true }],
 			},
 			fileParallelism: false,
@@ -920,12 +921,22 @@ export default defineConfig(
 import dts from 'vite-plugin-dts'
 import { srcBrowser, resolveWorkspacePath } from '../../vite.config.ts'
 
+// vite-plugin-dts rolls this face into one declaration, and the roll-up reaches
+// src/core through a relative source path the tarball does not carry. The path
+// keeps each source module's own depth, so a module in a browser subfolder emits
+// one that leaves dist/src entirely. The rewrite below externalizes core through
+// the package's own published root export, on the final roll-up only.
 export default defineConfig(
 	srcBrowser({
 		plugins: [
 			dts({
 				tsconfigPath: resolveWorkspacePath('configs/src/tsconfig.browser.json'),
 				bundleTypes: true,
+				beforeWriteFile: (path, content) => ({
+					content: /[\\\\/]dist[\\\\/]src[\\\\/]browser[\\\\/]index\\.d\\.ts$/.test(path)
+{{replacement}}
+						: content,
+				}),
 			}),
 		],
 	}),
@@ -994,7 +1005,319 @@ import { appShowcase } from '../../vite.config.ts'
 export default defineConfig(appShowcase())
 `
 		})
-	})
+	}),
+	browsers: `// A generated browser workspace resolves its own Chromium here rather than in
+// \`configs/helpers.ts\`, because that leaf is vendored byte-identical to every
+// workspace and most of them declare no \`playwright\` to import.
+
+import type { PlaywrightProviderOptions } from '@vitest/browser-playwright'
+import { chromium } from 'playwright'
+import { accessSync, constants as FS_CONSTANTS, globSync, readdirSync, statSync } from 'node:fs'
+import { basename, dirname, join, resolve as resolvePath } from 'node:path'
+
+/**
+ * Chromium executable layouts inside a \`chromium-<revision>\` browsers-directory entry, per
+ * platform.
+ *
+ * @remarks
+ * The current Playwright build ships Chrome for Testing on macOS. The trailing \`Chromium.app\`
+ * layouts are what earlier builds shipped, so the list spans Playwright versions instead of
+ * pinning to the installed one.
+ */
+export const CHROMIUM_LAYOUTS = Object.freeze([
+	'chrome-linux/chrome',
+	'chrome-linux64/chrome',
+	'chrome-win/chrome.exe',
+	'chrome-win64/chrome.exe',
+	'chrome-mac-x64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',
+	'chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',
+	'chrome-mac/Chromium.app/Contents/MacOS/Chromium',
+	'chrome-mac-arm64/Chromium.app/Contents/MacOS/Chromium',
+])
+
+/** The \`chromium-<revision>\` entry name Playwright installs one managed build into. */
+export const CHROMIUM_ENTRY_PATTERN = /^chromium-\\d+$/
+
+/** The revision number carried by any path containing a \`chromium-<revision>\` segment. */
+export const CHROMIUM_REVISION_PATTERN = /chromium-(\\d+)/
+
+/** The directory a managed Linux container installs its bundled Playwright browsers into. */
+export const BUNDLED_BROWSERS_ROOT = '/opt/pw-browsers'
+
+/**
+ * Bundled Chromium layouts under the managed-container browsers root, as glob patterns.
+ *
+ * @remarks
+ * The revision directory and its inner layout both drift across Playwright builds, and the
+ * container also carries a top-level \`chromium\` alias, so every known shape is globbed.
+ */
+export const BUNDLED_CHROMIUM_LAYOUTS = Object.freeze([
+	'chromium',
+	'chromium-*/chrome-linux64/chrome',
+	'chromium-*/chrome-linux/chrome',
+])
+
+/** Stable Playwright Chromium channels and their standard executable layouts. */
+export const SYSTEM_BROWSER_CHANNELS = Object.freeze([
+	Object.freeze({
+		channel: 'chrome',
+		layouts: Object.freeze({
+			linux: '/opt/google/chrome/chrome',
+			darwin: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+			win32: Object.freeze(['Google', 'Chrome', 'Application', 'chrome.exe']),
+		}),
+	}),
+	Object.freeze({
+		channel: 'msedge',
+		layouts: Object.freeze({
+			linux: '/opt/microsoft/msedge/msedge',
+			darwin: '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+			win32: Object.freeze(['Microsoft', 'Edge', 'Application', 'msedge.exe']),
+		}),
+	}),
+])
+
+/**
+ * Determine whether a path identifies an executable regular file.
+ *
+ * @param path - The filesystem path to inspect.
+ * @returns Whether the path is a regular file with execute access.
+ *
+ * @example
+ * \`\`\`ts
+ * isBrowserExecutable('/opt/google/chrome/chrome')
+ * \`\`\`
+ */
+export function isBrowserExecutable(path: string): boolean {
+	try {
+		if (!statSync(path).isFile()) return false
+		accessSync(path, FS_CONSTANTS.X_OK)
+		return true
+	} catch {
+		return false
+	}
+}
+
+/**
+ * Order two Chromium paths so the highest revision sorts first.
+ *
+ * @param left - The first path or directory entry to compare.
+ * @param right - The second path or directory entry to compare.
+ * @returns A negative number when \`left\` sorts first, positive when \`right\` does.
+ *
+ * @remarks
+ * Revisions are numbers, so \`chromium-1200\` outranks \`chromium-999\` despite sorting below it
+ * lexically. A path carrying no revision falls back to descending name order.
+ *
+ * @example
+ * \`\`\`ts
+ * ['chromium-999', 'chromium-1200'].sort(compareRevisions)
+ * \`\`\`
+ */
+export function compareRevisions(left: string, right: string): number {
+	const leftRevision = CHROMIUM_REVISION_PATTERN.exec(left)?.[1]
+	const rightRevision = CHROMIUM_REVISION_PATTERN.exec(right)?.[1]
+	if (leftRevision === undefined || rightRevision === undefined) return right.localeCompare(left)
+	return Number(rightRevision) - Number(leftRevision)
+}
+
+/**
+ * Read the executable path of Playwright's pinned Chromium revision.
+ *
+ * @returns The pinned executable path, or \`undefined\` when this platform has none.
+ *
+ * @remarks
+ * Playwright throws rather than returning a path when the current platform carries no initialized
+ * executable, and an unguarded call would fail configuration evaluation for every project.
+ *
+ * @example
+ * \`\`\`ts
+ * resolvePinnedBrowser()
+ * \`\`\`
+ */
+export function resolvePinnedBrowser(): string | undefined {
+	try {
+		const pinned = chromium.executablePath()
+		return pinned.length === 0 ? undefined : pinned
+	} catch {
+		return undefined
+	}
+}
+
+/**
+ * Resolve a launchable Playwright-managed Chromium executable: the pinned revision when installed,
+ * otherwise a \`chromium\` / \`chromium.exe\` alias or any other \`chromium-*\` revision under the same
+ * Playwright browsers directory. A pinned-revision miss is not Chromium absence — managed
+ * containers ship one usable build, often behind a revision-agnostic alias, for many Playwright
+ * versions.
+ *
+ * @param pinned - The executable path for Playwright's pinned Chromium revision.
+ * @returns The managed executable path, or \`undefined\` when none is executable.
+ *
+ * @example
+ * \`\`\`ts
+ * resolveManagedBrowser('/root/.cache/ms-playwright/chromium-1234/chrome-linux64/chrome')
+ * \`\`\`
+ */
+export function resolveManagedBrowser(pinned: string): string | undefined {
+	if (isBrowserExecutable(pinned)) return pinned
+	let revisionRoot = dirname(pinned)
+	for (;;) {
+		if (CHROMIUM_ENTRY_PATTERN.test(basename(revisionRoot))) break
+		const parent = dirname(revisionRoot)
+		if (parent === revisionRoot) return undefined
+		revisionRoot = parent
+	}
+	const browsersRoot = dirname(revisionRoot)
+	for (const alias of ['chromium', 'chromium.exe']) {
+		const candidate = resolvePath(browsersRoot, alias)
+		if (isBrowserExecutable(candidate)) return candidate
+	}
+	let entries: readonly string[]
+	try {
+		entries = readdirSync(browsersRoot)
+	} catch {
+		return undefined
+	}
+	const revisions = entries
+		.filter((entry) => CHROMIUM_ENTRY_PATTERN.test(entry))
+		.sort(compareRevisions)
+	for (const revision of revisions) {
+		for (const layout of CHROMIUM_LAYOUTS) {
+			const candidate = resolvePath(browsersRoot, revision, layout)
+			if (isBrowserExecutable(candidate)) return candidate
+		}
+	}
+	return undefined
+}
+
+/**
+ * Resolve the Chromium a managed Linux container bundles outside the Playwright cache.
+ *
+ * @param platform - The Node platform the container runs on.
+ * @param root - The bundled browsers directory to search.
+ * @returns The highest matching executable path, or \`undefined\` when none is executable.
+ *
+ * @example
+ * \`\`\`ts
+ * resolveBundledBrowser('linux', BUNDLED_BROWSERS_ROOT)
+ * \`\`\`
+ */
+export function resolveBundledBrowser(platform: NodeJS.Platform, root: string): string | undefined {
+	if (platform !== 'linux') return undefined
+	for (const layout of BUNDLED_CHROMIUM_LAYOUTS) {
+		let matches: readonly string[]
+		try {
+			matches = globSync(layout, { cwd: root })
+		} catch {
+			return undefined
+		}
+		for (const match of [...matches].sort(compareRevisions)) {
+			const candidate = resolvePath(root, match)
+			if (isBrowserExecutable(candidate)) return candidate
+		}
+	}
+	return undefined
+}
+
+/**
+ * Resolve the first installed stable system Chromium channel.
+ *
+ * @param platform - The Node platform whose standard layouts should be probed.
+ * @param environment - The process environment supplying Windows installation roots.
+ * @returns \`chrome\`, then \`msedge\`, or \`undefined\` when neither is executable.
+ *
+ * @example
+ * \`\`\`ts
+ * resolveSystemBrowser(process.platform, process.env)
+ * \`\`\`
+ */
+export function resolveSystemBrowser(
+	platform: NodeJS.Platform,
+	environment: NodeJS.ProcessEnv,
+): string | undefined {
+	if (platform !== 'linux' && platform !== 'darwin' && platform !== 'win32') return undefined
+	const roots = new Set<string>()
+	if (platform === 'win32') {
+		for (const root of [
+			environment.LOCALAPPDATA,
+			environment.PROGRAMFILES,
+			environment['PROGRAMFILES(X86)'],
+		]) {
+			if (root !== undefined && root.length > 0) roots.add(root)
+		}
+		const homeDrive = environment.HOMEDRIVE
+		if (homeDrive !== undefined && homeDrive.length > 0) {
+			roots.add(join(homeDrive, 'Program Files'))
+			roots.add(join(homeDrive, 'Program Files (x86)'))
+		}
+	}
+	for (const browser of SYSTEM_BROWSER_CHANNELS) {
+		if (platform === 'win32') {
+			for (const root of roots) {
+				if (isBrowserExecutable(join(root, ...browser.layouts.win32))) return browser.channel
+			}
+			continue
+		}
+		if (isBrowserExecutable(browser.layouts[platform])) return browser.channel
+	}
+	return undefined
+}
+
+/**
+ * Resolve Playwright provider options for whatever browser this host can actually launch.
+ *
+ * @param pinned - The executable path for Playwright's pinned Chromium revision, when it has one.
+ * @param platform - The Node platform whose standard layouts should be probed.
+ * @param environment - The process environment supplying operator overrides and Windows roots.
+ * @param root - The managed-container bundled browsers directory to search.
+ * @returns Provider options naming an executable, a WebSocket endpoint, or a channel.
+ *
+ * @remarks
+ * Precedence, most important first: \`PLAYWRIGHT_EXECUTABLE_PATH\`, \`PLAYWRIGHT_WS_ENDPOINT\`,
+ * \`PLAYWRIGHT_CHANNEL\`, the managed Playwright Chromium, the container's bundled Chromium, a
+ * verified system channel, then the platform default channel. An operator override outranks
+ * discovery and is returned exactly as given: none of those three environment values is checked
+ * against the filesystem, because verifying an override would defeat the override. The pinned
+ * managed revision outranks anything found on the host because it is deterministic. The installed
+ * pinned revision returns empty options so Playwright keeps its own default launch semantics. Only
+ * a discovered system channel is verified before it is named. The platform default is unverified
+ * as well and exists only as a last resort: Windows takes \`msedge\`, which ships with the OS and
+ * never collides with a foreground Chrome.
+ *
+ * @example
+ * \`\`\`ts
+ * resolveBrowser(resolvePinnedBrowser(), process.platform, process.env)
+ * \`\`\`
+ */
+export function resolveBrowser(
+	pinned: string | undefined,
+	platform: NodeJS.Platform,
+	environment: NodeJS.ProcessEnv,
+	root: string = BUNDLED_BROWSERS_ROOT,
+): PlaywrightProviderOptions {
+	const executable = environment.PLAYWRIGHT_EXECUTABLE_PATH
+	if (executable !== undefined && executable.length > 0) {
+		return { launchOptions: { executablePath: executable } }
+	}
+	const endpoint = environment.PLAYWRIGHT_WS_ENDPOINT
+	if (endpoint !== undefined && endpoint.length > 0) {
+		return { connectOptions: { wsEndpoint: endpoint } }
+	}
+	const requested = environment.PLAYWRIGHT_CHANNEL
+	if (requested !== undefined && requested.length > 0) {
+		return { launchOptions: { channel: requested } }
+	}
+	const managed = pinned === undefined ? undefined : resolveManagedBrowser(pinned)
+	if (managed !== undefined) {
+		return managed === pinned ? {} : { launchOptions: { executablePath: managed } }
+	}
+	const bundled = resolveBundledBrowser(platform, root)
+	if (bundled !== undefined) return { launchOptions: { executablePath: bundled } }
+	const fallback = platform === 'win32' ? 'msedge' : 'chrome'
+	return { launchOptions: { channel: resolveSystemBrowser(platform, environment) ?? fallback } }
+}
+`
 });
 /**
 * Formatter-stable template text for source, test, document, guide, and service artifacts.
@@ -2075,6 +2398,46 @@ function nameToGuide(name) {
 	return `guides/${name.slice(name.lastIndexOf("/") + 1)}.md`;
 }
 /**
+* Derive the declaration rewrite a published face's `beforeWriteFile` applies.
+*
+* @param name - The workspace's own bare package name.
+* @returns The ternary consequent an emitted `vite.{browser,server}.config.ts`
+* fills its `{{replacement}}` span with, indented for that span.
+*
+* @remarks
+* `vite-plugin-dts` rolls a face into one declaration and keeps each source
+* module's own relative depth, so a nested module emits a path that escapes
+* `dist/src` and a flat one resolves only by luck. Both faces rewrite the same
+* relative core path to the package's published root export, so the branch is
+* derived once here. The extension alternation is what the two permitted import
+* spellings produce: an `@src/core` alias resolves to the core source module and
+* prints `.ts`, while a relative import prints the `.js` specifier it was
+* written with. The formatter keeps the call on one line only while the line it
+* prints measures inside the vendored width, and the workspace name is what
+* varies, so the shape is chosen by measuring the candidate: a tab prints as the
+* vendored two columns, and the gate admits a name long enough to push the
+* joined call past 100.
+*
+* @example
+* ```ts
+* import { nameToRewrite } from '@orkestrel/scaffold'
+*
+* nameToRewrite('router').includes("'@orkestrel/router'") // true
+* ```
+*/
+function nameToRewrite(name) {
+	const specifier = serializeTypeScriptString(`@orkestrel/${name}`);
+	const pattern = "/(?:\\.\\.\\/)+core\\/index\\.[jt]s/g";
+	const joined = `\t\t\t\t\t\t? content.replaceAll(${pattern}, ${specifier})`;
+	if (joined.replaceAll("	", "  ").length <= 100) return joined;
+	return [
+		"						? content.replaceAll(",
+		`\t\t\t\t\t\t\t\t${pattern},`,
+		`\t\t\t\t\t\t\t\t${specifier},`,
+		"							)"
+	].join("\n");
+}
+/**
 * Select the host paths a named workspace vendors.
 *
 * @param paths - The candidate host paths, in their declared order.
@@ -3012,7 +3375,8 @@ function blueprintToRootVite(blueprint) {
 		factories.push((0, _orkestrel_template.fillTemplate)(CONFIG_TEMPLATES.factories.src.browser, {
 			external: core ? "external: (id: string) => id === '@src/core' || id.startsWith('@orkestrel/')," : "external: (id: string) => id.startsWith('@orkestrel/'),",
 			output: core ? "					output: { paths: { '@src/core': '../core/index.js' } }," : "					output: {},",
-			exclude: core ? "				exclude: ['tests/src/core/**/*.test.ts'],\n" : ""
+			exclude: core ? "				exclude: ['tests/src/core/**/*.test.ts'],\n" : "",
+			global: blueprint.global ? "				globalSetup: ['./tests/setupGlobal.ts'],\n" : ""
 		}));
 		projects.push("srcBrowser");
 	}
@@ -3133,6 +3497,8 @@ ${projects.map((project) => `\t\t\t${project},`).join("\n")}
 		viteTypes: machinery.showcase ? "PluginOption, UserConfig" : "UserConfig",
 		imports: imports.length === 0 ? "" : `${imports.join("\n")}\n`,
 		helpers: boundaries.length === 0 ? "" : `import { ${boundaries.join(", ")} } from './configs/helpers.js'\n`,
+		browsers: machinery.browser ? "import { resolveBrowser, resolvePinnedBrowser } from './configs/browsers.js'\n" : "",
+		options: machinery.browser ? "const browserOptions = resolveBrowser(resolvePinnedBrowser(), process.platform, process.env)\n\n" : "",
 		factories: body,
 		projects: projectRows
 	});
@@ -3166,22 +3532,20 @@ function blueprintToConfigArtifacts(blueprint) {
 		origin: "template",
 		content: blueprintToRootVite(blueprint)
 	}];
+	if (blueprintToMachinery(blueprint).browser) artifacts.push({
+		path: "configs/browsers.ts",
+		group: "configs",
+		ownership: "content",
+		origin: "template",
+		content: CONFIG_TEMPLATES.browsers
+	});
 	for (const environment of blueprint.src) for (const path of SRC_MATRIX[environment].configs) {
 		let content = CONFIG_TEMPLATES.vites.src.core;
 		if (path === "configs/src/tsconfig.core.json") content = CONFIG_TEMPLATES.tsconfigs.src.core;
-		else if (path === "configs/src/vite.browser.config.ts") content = CONFIG_TEMPLATES.vites.src.browser;
+		else if (path === "configs/src/vite.browser.config.ts") content = (0, _orkestrel_template.fillTemplate)(CONFIG_TEMPLATES.vites.src.browser, { replacement: nameToRewrite(blueprint.name) });
 		else if (path === "configs/src/tsconfig.browser.json") content = CONFIG_TEMPLATES.tsconfigs.src.browser;
-		else if (path === "configs/src/vite.server.config.ts") {
-			const packageName = serializeTypeScriptString(`@orkestrel/${blueprint.name}`);
-			const joined = `\t\t\t\t\t\t? content.replaceAll(/(?:\\.\\.\\/)+core\\/index\\.ts/g, ${packageName})`;
-			const replacement = joined.replaceAll("	", "  ").length <= 100 ? joined : [
-				"						? content.replaceAll(",
-				"								/(?:\\.\\.\\/)+core\\/index\\.ts/g,",
-				`\t\t\t\t\t\t\t\t${packageName},`,
-				"							)"
-			].join("\n");
-			content = (0, _orkestrel_template.fillTemplate)(CONFIG_TEMPLATES.vites.src.server, { replacement });
-		} else if (path === "configs/src/tsconfig.server.json") content = CONFIG_TEMPLATES.tsconfigs.src.server;
+		else if (path === "configs/src/vite.server.config.ts") content = (0, _orkestrel_template.fillTemplate)(CONFIG_TEMPLATES.vites.src.server, { replacement: nameToRewrite(blueprint.name) });
+		else if (path === "configs/src/tsconfig.server.json") content = CONFIG_TEMPLATES.tsconfigs.src.server;
 		artifacts.push({
 			path,
 			group: "configs",
@@ -4531,6 +4895,7 @@ exports.matchesOrchestrationPath = matchesOrchestrationPath;
 exports.matchesRange = matchesRange;
 exports.nameToGuide = nameToGuide;
 exports.nameToHostArtifacts = nameToHostArtifacts;
+exports.nameToRewrite = nameToRewrite;
 exports.overridesToQuestions = overridesToQuestions;
 exports.parseBlueprint = parseBlueprint;
 exports.parseCompilerOptions = parseCompilerOptions;