@orkestrel/scaffold 0.0.15 → 0.0.17

package/dist/src/core/index.d.cts

@@ -1177,7 +1177,7 @@ export declare function coreViteConfig(): string;
      readonly content: string;
      readonly freshness: Freshness;
      readonly note?: string;
-     /** SHA-256 of the observed local mirror, or `absent`; omitted outside target-aware pulls. */
+     /** SHA-256 of the observed local mirror, or `absent`; omitted outside target-aware synchronization. */
      readonly baseline?: string;
  }
 
@@ -2275,7 +2275,7 @@ export declare function coreViteConfig(): string;
  export declare function rootViteConfig(src: readonly Environment[], facts?: ViteFacts): string;
 
  /** The devDependency range generated packages pin `@orkestrel/scaffold` at. */
- export declare const SCAFFOLD_RANGE = "^0.0.15";
+ export declare const SCAFFOLD_RANGE = "^0.0.17";
 
  /**
   * Carries a `ScaffoldErrorCode` + optional `context` (AGENTS §12).
@@ -2537,7 +2537,7 @@ export declare function coreViteConfig(): string;
  export declare const SYNC_BASELINE_PATTERN: RegExp;
 
  /**
-  * The whole outcome of a `Sync.pull`.
+  * The whole outcome of a `Sync.pull` or `Sync.mirror` synchronization.
   *
   * @remarks
   * `clean` is `true` iff no drift AND no failures; `failed` is the count of

package/dist/src/core/index.d.ts

@@ -1177,7 +1177,7 @@ export declare function coreViteConfig(): string;
      readonly content: string;
      readonly freshness: Freshness;
      readonly note?: string;
-     /** SHA-256 of the observed local mirror, or `absent`; omitted outside target-aware pulls. */
+     /** SHA-256 of the observed local mirror, or `absent`; omitted outside target-aware synchronization. */
      readonly baseline?: string;
  }
 
@@ -2275,7 +2275,7 @@ export declare function coreViteConfig(): string;
  export declare function rootViteConfig(src: readonly Environment[], facts?: ViteFacts): string;
 
  /** The devDependency range generated packages pin `@orkestrel/scaffold` at. */
- export declare const SCAFFOLD_RANGE = "^0.0.15";
+ export declare const SCAFFOLD_RANGE = "^0.0.17";
 
  /**
   * Carries a `ScaffoldErrorCode` + optional `context` (AGENTS §12).
@@ -2537,7 +2537,7 @@ export declare function coreViteConfig(): string;
  export declare const SYNC_BASELINE_PATTERN: RegExp;
 
  /**
-  * The whole outcome of a `Sync.pull`.
+  * The whole outcome of a `Sync.pull` or `Sync.mirror` synchronization.
   *
   * @remarks
   * `clean` is `true` iff no drift AND no failures; `failed` is the count of

package/dist/src/core/index.js

@@ -226,7 +226,7 @@ var DEFAULT_VERSION = "0.0.1";
 /** The `engines.node` range the `blueprint` builder fills. */
 var DEFAULT_ENGINES = `>=${MINIMUM_NODE_VERSION}`;
 /** The devDependency range generated packages pin `@orkestrel/scaffold` at. */
-var SCAFFOLD_RANGE = "^0.0.15";
+var SCAFFOLD_RANGE = "^0.0.17";
 /** Tooling versions shared by scaffold and every generated workspace. */
 var BASE_DEV_DEPENDENCIES = Object.freeze({
 	"@microsoft/api-extractor": "^7.58.12",
@@ -4139,9 +4139,7 @@ ${EXPORT_KEYWORD} ${FUNCTION_KEYWORD} isBrowserVuePath(path: string): boolean {
 		content: `import { globSync{{browserPolicySpecifier}} } from 'node:fs'
 import { describe, expect, it } from 'vitest'
 import { isBrowserVuePath } from './setup.js'
-import { inspectCodingWorkspace } from './setupPolicy.js'
-{{browserPolicyImport}}
-{{vuePolicyImport}}
+import { inspectCodingWorkspace } from './setupPolicy.js'{{browserPolicyImport}}{{vuePolicyImport}}
 
 describe('repository coding law', () => {
 	it('keeps Vue single-file components exclusively in browser environments', () => {
@@ -4152,8 +4150,7 @@ describe('repository coding law', () => {
 
 	it('enforces source placement, exports, readonly contracts, and syntax law', () => {
 		{{workspacePolicyAssertion}}
-	})
-{{browserPolicyTest}}
+	}){{browserPolicyTest}}
 })
 `
 	}),
@@ -5875,7 +5872,7 @@ ${renderedProjects}
 ${fitsPrintWidth(inlineRegistrations) ? inlineRegistrations : `		[
 ${renderedRegistrations.map((registration) => `			${registration},`).join("\n")}
 		],`}
-		chromiumPath !== undefined,
+		browserOptions !== undefined,
 		process.argv,
 	),`;
 }
@@ -5899,6 +5896,8 @@ ${renderedRegistrations.map((registration) => `			${registration},`).join("\n")}
 */
 function viteHeader(machinery) {
 	const { browser: needsBrowser, vue: needsVue, output: needsOutput } = machinery;
+	const playwrightTypeImports = needsBrowser ? `import type { PlaywrightProviderOptions } from '@vitest/browser-playwright'
+` : "";
 	const playwrightImports = needsBrowser ? `import { playwright } from '@vitest/browser-playwright'
 import { chromium } from 'playwright'
 ` : "";
@@ -6209,7 +6208,9 @@ import { parse as parseVue } from 'vue/compiler-sfc'
 									? undefined
 									: packageRootOf(packageName, physicalSource)
 							if (packageRoot === undefined || !containedPath(packageRoot, physicalSource)) {
-								this.error('Resolved dependencies must remain inside their physical package root')
+								return this.error(
+									'Resolved dependencies must remain inside their physical package root',
+								)
 							}
 							trustedPackageRoots.add(packageRoot)
 						}
@@ -6217,7 +6218,7 @@ import { parse as parseVue } from 'vue/compiler-sfc'
 					}
 					const resolvedSource = workspacePath(physicalSource)
 					if (resolvedSource === undefined) {
-						this.error('Environment modules cannot import files outside the workspace')
+						return this.error('Environment modules cannot import files outside the workspace')
 					}
 					const assetError = environmentPathError(owner, resolvedSource)
 					if (assetError !== undefined) this.error(assetError)
@@ -7246,7 +7247,7 @@ ${needsVue ? `		configureServer(server) {
 	}
 }
 `;
-	return `${viteTypeImports}
+	return `${playwrightTypeImports}${viteTypeImports}
 ${needsBrowser ? `import { isCSSRequest, parseSync, preprocessCSS, transformWithOxc, Visitor } from 'vite'
 ` : `import { parseSync, transformWithOxc, Visitor } from 'vite'
 `}import { defineConfig, mergeConfig } from 'vitest/config'
@@ -7254,7 +7255,7 @@ import tsconfig from './tsconfig.json' with { type: 'json' }
 import { fileURLToPath, URL } from 'node:url'
 import { isBuiltin } from 'node:module'
 import {
-	closeSync,
+${needsBrowser ? "	accessSync,\n" : ""}	closeSync,
 	constants as FS_CONSTANTS,
 	existsSync,
 	fstatSync,
@@ -7263,7 +7264,15 @@ import {
 ${needsBrowser ? "	readdirSync,\n" : ""}	readSync,
 	realpathSync,
 ${needsBrowser ? "	statSync,\n" : ""}} from 'node:fs'
-import { ${needsBrowser ? "basename, " : ""}dirname, isAbsolute, relative, resolve as resolvePath, sep } from 'node:path'
+${needsBrowser ? `import {
+	basename,
+	join,
+	dirname,
+	isAbsolute,
+	relative,
+	resolve as resolvePath,
+	sep,
+} from 'node:path'` : `import { dirname, isAbsolute, relative, resolve as resolvePath, sep } from 'node:path'`}
 ${playwrightImports}${vueImports}${needsBrowser ? `\n/** Chromium executable layouts inside a \`chromium-<revision>\` browsers-directory entry, per platform. */
 ${EXPORT_KEYWORD} ${CONST_KEYWORD} CHROMIUM_LAYOUTS = Object.freeze([
 	'chrome-linux/chrome',
@@ -7274,15 +7283,64 @@ ${EXPORT_KEYWORD} ${CONST_KEYWORD} CHROMIUM_LAYOUTS = Object.freeze([
 	'chrome-mac-arm64/Chromium.app/Contents/MacOS/Chromium',
 ])
 
+/** Stable Playwright Chromium channels and their standard executable layouts. */
+${EXPORT_KEYWORD} ${CONST_KEYWORD} 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_KEYWORD} function isBrowserExecutable(path: string): boolean {
+	try {
+		if (!statSync(path).isFile()) return false
+		accessSync(path, FS_CONSTANTS.X_OK)
+		return true
+	} catch {
+		return false
+	}
+}
+
 /**
- * Resolve a launchable Chromium executable: the pinned revision when installed,
+ * 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(chromium.executablePath())
+ * \`\`\`
  */
-${EXPORT_KEYWORD} function resolveChromium(pinned: string): string | undefined {
-	if (existsSync(pinned)) return pinned
+${EXPORT_KEYWORD} function resolveManagedBrowser(pinned: string): string | undefined {
+	if (isBrowserExecutable(pinned)) return pinned
 	let revisionRoot = dirname(pinned)
 	for (;;) {
 		if (/^chromium-\\d+$/.test(basename(revisionRoot))) break
@@ -7293,7 +7351,7 @@ ${EXPORT_KEYWORD} function resolveChromium(pinned: string): string | undefined {
 	const browsersRoot = dirname(revisionRoot)
 	for (const alias of ['chromium', 'chromium.exe']) {
 		const candidate = resolvePath(browsersRoot, alias)
-		if (existsSync(candidate) && statSync(candidate).isFile()) return candidate
+		if (isBrowserExecutable(candidate)) return candidate
 	}
 	let entries: readonly string[]
 	try {
@@ -7307,18 +7365,89 @@ ${EXPORT_KEYWORD} function resolveChromium(pinned: string): string | undefined {
 	for (const revision of revisions) {
 		for (const layout of CHROMIUM_LAYOUTS) {
 			const candidate = resolvePath(browsersRoot, revision, layout)
-			if (existsSync(candidate)) return candidate
+			if (isBrowserExecutable(candidate)) return candidate
 		}
 	}
 	return undefined
 }
 
-${CONST_KEYWORD} chromiumPinned = chromium.executablePath()
-${CONST_KEYWORD} chromiumPath = resolveChromium(chromiumPinned)
-${CONST_KEYWORD} chromiumOptions =
-	chromiumPath === undefined || chromiumPath === chromiumPinned
-		? {}
-		: { launchOptions: { executablePath: chromiumPath } }
+/**
+ * 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_KEYWORD} 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 launch options for a managed Chromium or stable system browser.
+ *
+ * @param pinned - The executable path for Playwright's pinned Chromium revision.
+ * @param platform - The Node platform whose standard system layouts should be probed.
+ * @param environment - The process environment supplying Windows installation roots.
+ * @returns Provider options for managed Chromium, Chrome, or Edge, or \`undefined\`.
+ *
+ * @remarks
+ * An installed pinned revision returns an empty object so Playwright retains
+ * its default launch semantics. A different managed executable is selected by
+ * path; a system browser is selected by its stable Playwright channel.
+ *
+ * @example
+ * \`\`\`ts
+ * resolveBrowser(chromium.executablePath(), process.platform, process.env)
+ * \`\`\`
+ */
+${EXPORT_KEYWORD} function resolveBrowser(
+	pinned: string,
+	platform: NodeJS.Platform,
+	environment: NodeJS.ProcessEnv,
+): PlaywrightProviderOptions | undefined {
+	const managed = resolveManagedBrowser(pinned)
+	if (managed !== undefined) {
+		return managed === pinned ? {} : { launchOptions: { executablePath: managed } }
+	}
+	const channel = resolveSystemBrowser(platform, environment)
+	return channel === undefined ? undefined : { launchOptions: { channel } }
+}
+
+${CONST_KEYWORD} browserPinned = chromium.executablePath()
+${CONST_KEYWORD} browserOptions = resolveBrowser(browserPinned, process.platform, process.env)
 ` : ""}
 ${EXPORT_KEYWORD} function resolveWorkspacePath(relativePath: string): string {
 	return fileURLToPath(new URL(relativePath, import.meta.url))
@@ -7367,7 +7496,9 @@ ${needsBrowser ? `${EXPORT_KEYWORD} function gateBrowserProjects(
 		projects.push(registration.project())
 	}
 	if (gated.length === 0) return { projects }
-	console.warn(\`browser projects skipped: Chromium absent (\${gated.join(', ')})\`)
+	console.warn(
+		\`browser projects skipped: no Playwright Chromium, Chrome, or Edge found (\${gated.join(', ')})\`,
+	)
 	const filters: string[] = []
 	let readable = true
 	for (let index = 0; index < argv.length; index += 1) {
@@ -7658,7 +7789,7 @@ ${EXPORT_KEYWORD} const srcBrowser = (config?: UserConfig): UserConfig =>
 						}),
 				browser: {
 					enabled: true,
-					provider: playwright(chromiumOptions),
+					provider: playwright(browserOptions),
 					instances: [{ browser: 'chromium', headless: true }],
 				},
 				fileParallelism: false,
@@ -7790,7 +7921,7 @@ ${EXPORT_KEYWORD} const srcBrowser = (config?: UserConfig): UserConfig =>
 							}),
 					browser: {
 						enabled: true,
-						provider: playwright(chromiumOptions),
+						provider: playwright(browserOptions),
 						instances: [{ browser: 'chromium', headless: true }],
 					},
 					fileParallelism: false,
@@ -7955,7 +8086,7 @@ ${EXPORT_KEYWORD} const srcBrowser = (config?: UserConfig): UserConfig =>
 						}),
 				browser: {
 					enabled: true,
-					provider: playwright(chromiumOptions),
+					provider: playwright(browserOptions),
 					instances: [{ browser: 'chromium', headless: true }],
 				},
 				fileParallelism: false,
@@ -8084,7 +8215,7 @@ ${EXPORT_KEYWORD} function appBrowser(...config: readonly never[]): UserConfig {
 			},
 			browser: {
 				enabled: true,
-				provider: playwright(chromiumOptions),
+				provider: playwright(browserOptions),
 				instances: [{ browser: 'chromium', headless: true }],
 			},
 			fileParallelism: false,
@@ -8651,9 +8782,8 @@ function paritySpecifiers(spec) {
 function testArtifacts(spec, pascal) {
 	const hasBrowser = spec.src.includes("browser") || spec.app.includes("browser");
 	const hasVue = spec.app.includes("browser");
-	const browserPolicySpecifier = hasBrowser ? ", accessSync, constants as FS_CONSTANTS, statSync" : "";
-	const browserPolicyImport = hasBrowser ? "import { chromium } from 'playwright'\nimport { resolveChromium } from '../vite.config.js'" : "";
-	const vuePolicyImport = hasVue ? "import { parse as parseVue } from 'vue/compiler-sfc'" : "";
+	const browserPolicyImport = hasBrowser ? "\nimport { chromium } from 'playwright'\nimport { isBrowserExecutable, resolveBrowser, SYSTEM_BROWSER_CHANNELS } from '../vite.config.js'" : "";
+	const vuePolicyImport = hasVue ? "\nimport { parse as parseVue } from 'vue/compiler-sfc'" : "";
 	const workspacePolicyAssertion = hasVue ? `expect(
 			inspectCodingWorkspace(process.cwd(), (path, content) => {
 				const parsed = parseVue(content, { filename: path })
@@ -8664,15 +8794,21 @@ function testArtifacts(spec, pascal) {
 			}),
 		).toEqual([])` : "expect(inspectCodingWorkspace(process.cwd())).toEqual([])";
 	const browserPolicyTest = hasBrowser ? `
-	it('resolves Chromium only to a real executable file', () => {
-		const chromiumPath = resolveChromium(chromium.executablePath())
-		if (chromiumPath === undefined) return
 
-		expect(statSync(chromiumPath).isFile()).toBe(true)
-		expect(() => accessSync(chromiumPath, FS_CONSTANTS.X_OK)).not.toThrow()
+	it('resolves only a real managed executable or stable system browser channel', () => {
+		const options = resolveBrowser(chromium.executablePath(), process.platform, process.env)
+		let valid = options === undefined
+		if (options !== undefined) {
+			const channel = options.launchOptions?.channel
+			valid =
+				channel === undefined
+					? isBrowserExecutable(options.launchOptions?.executablePath ?? chromium.executablePath())
+					: SYSTEM_BROWSER_CHANNELS.some((browser) => browser.channel === channel)
+		}
+		expect(valid).toBe(true)
 	})` : "";
 	const artifacts = [fillArtifact("tests/setup.ts", "tests", "setup", {}), fillArtifact("tests/policy.test.ts", "tests", "policyTest", {
-		browserPolicySpecifier,
+		browserPolicySpecifier: "",
 		browserPolicyImport,
 		browserPolicyTest,
 		vuePolicyImport,