@joshuafolkken/kit 1.1370.0 → 1.1379.0

package/scripts/version/latest-update.ts

@@ -13,6 +13,7 @@ import { overrides_check } from '#scripts/overrides/overrides-logic'
 import { execaSync } from 'execa'
 import { fresh_metadata_cache } from './fresh-metadata-cache'
 import { latest_regression, type VersionRegression } from './latest-regression'
+import { playwright_browsers } from './playwright-browsers'
 import { safe_chain_version_update } from './safe-chain-version-update'
 
 const PACKAGE_JSON_PATH = 'package.json'
@@ -164,23 +165,36 @@ function report_lockfile_overrides(): void {
 	process.exitCode = 1
 }
 
+// The browsers follow what `node_modules` holds, not how the update ended: a later stage failing
+// after `@playwright/test` moved, and a rollback — which restores the manifest and the lockfile but
+// leaves the newer package installed — both leave a Playwright whose browsers were never downloaded,
+// and the browser tests that run next would fail with "Executable doesn't exist".
+function install_browsers(playwright_version: string | undefined): void {
+	if (playwright_browsers.install_when_needed(playwright_version) !== 0) process.exitCode = 1
+}
+
+// The sync acts on the versions the update settled on, so it runs neither after a failed update nor
+// after a rollback — the latter so the files really are left exactly as they were found: it rewrites
+// the workflows' pinned safe-chain installer, which would contradict the notice that nothing changed.
 function main(): void {
 	const snapshot = take_snapshot()
+	const playwright_version = playwright_browsers.read_installed_version()
 	const overrides = overrides_files.read_current_overrides()
 
 	report_excluded(overrides_check.list_excluded_package_names(overrides))
 
 	const outcome = update_without_downgrading(snapshot)
 
+	// A failed `pnpm update` fails the command: the `josh latest` chain and `josh adopt` both read the
+	// exit code, and a zero here would let them carry on over dependencies that were never updated.
+	if (outcome.status !== 0) process.exitCode = outcome.status
+
 	report_overrides(overrides)
 	report_lockfile_overrides()
 
-	// Skipped after a rollback so the tree really is left exactly as it was found — this sync rewrites
-	// the workflows' pinned safe-chain installer, which would contradict the notice that
-	// nothing changed.
-	if (outcome.status === 0 && !outcome.is_rolled_back) {
-		safe_chain_version_update.sync()
-	}
+	if (outcome.status === 0 && !outcome.is_rolled_back) safe_chain_version_update.sync()
+
+	install_browsers(playwright_version)
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) main()

package/scripts/version/peer-floor.ts

@@ -0,0 +1,99 @@
+import semver from 'semver'
+import { z } from 'zod'
+
+// A package built on a toolkit publishes its own `peerDependencies`, and a toolkit raising a peer
+// floor edits nobody's manifest but its own. `josh latest` rewrites `dependencies` and
+// `devDependencies` only, so the consumer keeps declaring a floor it no longer develops or verifies
+// against: a user on a version between the two floors satisfies the consumer's declaration and
+// breaks the toolkit's.
+
+interface LaggingPeer {
+	name: string
+	range: string
+	/** The installed toolkit as `name@version`, so the reader knows which release set the floor. */
+	toolkit: string
+	toolkit_range: string
+}
+
+const peer_manifest_schema = z.looseObject({
+	name: z.string().optional(),
+	version: z.string().optional(),
+	peerDependencies: z.record(z.string(), z.string()).optional(),
+})
+
+type PeerManifest = z.infer<typeof peer_manifest_schema>
+
+function parse_manifest(package_json_content: string): PeerManifest {
+	return peer_manifest_schema.parse(JSON.parse(package_json_content))
+}
+
+// A range semver cannot read (`workspace:*`, `catalog:`) has no floor to compare, and neither does
+// one nothing can satisfy; both answer "not below" rather than inventing a violation.
+function is_floor_below(range: string, toolkit_range: string): boolean {
+	if (semver.validRange(range) === null || semver.validRange(toolkit_range) === null) return false
+
+	const floor = semver.minVersion(range)
+	const toolkit_floor = semver.minVersion(toolkit_range)
+
+	if (floor === null || toolkit_floor === null) return false
+
+	return semver.lt(floor, toolkit_floor)
+}
+
+function toolkit_label(toolkit: PeerManifest): string {
+	return [toolkit.name, toolkit.version].filter((part) => part !== undefined).join('@')
+}
+
+function to_lagging_peer(
+	[name, range]: [string, string],
+	toolkit: PeerManifest,
+): Array<LaggingPeer> {
+	const toolkit_range = toolkit.peerDependencies?.[name]
+
+	if (toolkit_range === undefined || !is_floor_below(range, toolkit_range)) return []
+
+	return [{ name, range, toolkit: toolkit_label(toolkit), toolkit_range }]
+}
+
+// A toolkit's own manifest is never compared with itself: there it is the source of the floors, not
+// a consumer of them.
+function find_lagging_against(manifest: PeerManifest, toolkit: PeerManifest): Array<LaggingPeer> {
+	if (manifest.name === toolkit.name) return []
+
+	return Object.entries(manifest.peerDependencies ?? {}).flatMap((entry) =>
+		to_lagging_peer(entry, toolkit),
+	)
+}
+
+// Every installed toolkit is compared, not kit alone: a package built on app-kit inherits app-kit's
+// floors exactly as app-kit inherits kit's, and the gap is the same one a tier up.
+function find_lagging(
+	package_json_content: string,
+	toolkit_json_contents: ReadonlyArray<string>,
+): Array<LaggingPeer> {
+	const manifest = parse_manifest(package_json_content)
+
+	return toolkit_json_contents.flatMap((content) =>
+		find_lagging_against(manifest, parse_manifest(content)),
+	)
+}
+
+function format_lagging(peer: LaggingPeer): string {
+	return `   ${peer.name}@${peer.range} — ${peer.toolkit} requires ${peer.toolkit_range}`
+}
+
+function format_failure(lagging: ReadonlyArray<LaggingPeer>): string {
+	return [
+		`\n✖ ${String(lagging.length)} published peer range(s) fall below an installed toolkit's:`,
+		...lagging.map((peer) => format_lagging(peer)),
+		'',
+		'   A user inside the gap satisfies this package and breaks the toolkit it is built on, so the',
+		'   declaration promises a combination nobody verified. Raise each `peerDependencies` floor',
+		'   in package.json to the range the toolkit requires.',
+	].join('\n')
+}
+
+const peer_floor = { find_lagging, format_failure }
+
+export { peer_floor }
+export type { LaggingPeer }

package/scripts/version/playwright-browsers.ts

@@ -0,0 +1,109 @@
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { json_value } from '#scripts/lib/json-value'
+import { file_reader } from '#scripts/lib/read-file'
+import { execaSync } from 'execa'
+import { z } from 'zod'
+
+// A Playwright release drives one exact browser build, so a bumped `@playwright/test` cannot launch
+// the browsers the previous version downloaded: every browser test fails with "Executable doesn't
+// exist" until `playwright install` runs. `josh latest` is what moves the version, so it is also
+// what has to leave the matching browsers behind — `josh adopt` runs the related tests right after
+// it, with nobody in between to run the install by hand (joshuafolkken/kit#3675).
+
+const INSTALLED_MANIFEST_PATH = path.join('node_modules', '@playwright', 'test', 'package.json')
+const INSTALLED_MANIFEST_SCHEMA = z.object({ version: z.string() })
+const BROWSERS_VARIABLE = 'JOSH_PLAYWRIGHT_BROWSERS'
+// Leading letter required: a value starting with a dash would reach the command as an option.
+const BROWSER_NAME_RE = /^[A-Za-z]/u
+const FAILURE_EXIT_CODE = 1
+const INSTALL_COMMAND: ReadonlyArray<string> = ['pnpm', 'exec', 'playwright', 'install']
+const DRY_RUN_FLAG = '--dry-run'
+const INSTALL_LOCATION_RE = /Install location: +(\S.*)/gu
+// Written last by `playwright install`, so a directory an interrupted download left behind lacks it.
+const COMPLETE_MARKER = 'INSTALLATION_COMPLETE'
+
+// Chromium alone, as the CI fallback installs: a bare `playwright install` fetches chromium, firefox
+// and webkit — roughly 1 GB — for the single chromium project kit scaffolds.
+const DEFAULT_BROWSERS: ReadonlyArray<string> = ['chromium']
+
+// The version actually installed, not the range in `package.json`: the browsers follow the resolved
+// release, and a repository without the package answers `undefined` on both sides of the update.
+function read_installed_version(): string | undefined {
+	const content = file_reader.read_file_or_empty(INSTALLED_MANIFEST_PATH)
+
+	return json_value.parse_with(content, INSTALLED_MANIFEST_SCHEMA)?.version
+}
+
+// The same variable name the CI workflow reads, sanitized the way its `tr -cd 'A-Za-z -'` does:
+// everything but letters, dashes and the whitespace between names is stripped out of a name rather
+// than the whole name dropped, so a mistyped `Chromium` or `chromium,firefox` reaches Playwright as
+// an unknown browser and fails at the install — never silently narrowed to chromium, which would
+// resurface later as a missing executable. A value with no usable name falls back to the default
+// rather than to a bare install.
+function resolve_browsers(environment: NodeJS.ProcessEnv = process.env): ReadonlyArray<string> {
+	const value = (environment[BROWSERS_VARIABLE] ?? '').replaceAll(/[^A-Za-z\s-]/gu, '')
+	const browsers = value.split(/\s+/u).filter((name) => BROWSER_NAME_RE.test(name))
+
+	return browsers.length > 0 ? browsers : DEFAULT_BROWSERS
+}
+
+// A branded channel (`chrome`, `msedge`) reports `<system>` instead of a directory Playwright owns;
+// there is nothing to look for, so it never counts as missing.
+function is_downloaded(location: string): boolean {
+	return !path.isAbsolute(location) || existsSync(path.join(location, COMPLETE_MARKER))
+}
+
+// Asks Playwright where the named browsers belong and whether each one is completely there. A
+// version comparison alone cannot tell: an install that failed or was interrupted leaves the next
+// run with the same version on both sides of the update and the browsers still absent, and that run
+// has to retry it rather than finish as if nothing were missing. A plan Playwright refuses counts as
+// missing, so the install runs and reports the refusal.
+function has_missing_browser(browsers: ReadonlyArray<string>): boolean {
+	const [cmd = '', ...rest] = [...INSTALL_COMMAND, DRY_RUN_FLAG, ...browsers]
+	const plan = execaSync(cmd, rest, { reject: false })
+	if (plan.exitCode !== 0) return true
+
+	const locations = [...plan.stdout.matchAll(INSTALL_LOCATION_RE)].map(
+		([, location = '']) => location,
+	)
+
+	return locations.some((location) => !is_downloaded(location))
+}
+
+function run_install(version: string, browsers: ReadonlyArray<string>): number {
+	const command = [...INSTALL_COMMAND, ...browsers]
+	const [cmd = '', ...rest] = command
+
+	console.info(`\n▶ ${command.join(' ')} (browsers for @playwright/test ${version})`)
+
+	const status = execaSync(cmd, rest, { stdio: 'inherit', reject: false }).exitCode
+	if (status === 0) return 0
+
+	console.error(
+		`\n✖ Playwright browser install failed (${command.join(' ')} exited ${String(status)}); browser tests cannot run until it succeeds.`,
+	)
+
+	return FAILURE_EXIT_CODE
+}
+
+// `before` is the version read ahead of the update. A moved version always installs; an unmoved one
+// installs only what an earlier run left missing, so a run that leaves Playwright alone with its
+// browsers in place costs no download. Nothing runs when the package is absent.
+function install_when_needed(before: string | undefined): number {
+	const after = read_installed_version()
+	if (after === undefined) return 0
+
+	const browsers = resolve_browsers()
+	if (after === before && !has_missing_browser(browsers)) return 0
+
+	return run_install(after, browsers)
+}
+
+const playwright_browsers = {
+	read_installed_version,
+	resolve_browsers,
+	install_when_needed,
+}
+
+export { playwright_browsers }

package/scripts/version/publishable-range-check.ts

@@ -1,13 +1,17 @@
 #!/usr/bin/env tsx
 /**
- * Release gate: every dependency range this package publishes must resolve for a consumer.
+ * Release gate: every dependency range this package publishes must resolve for a consumer, and no
+ * peer range it publishes may fall below an installed toolkit's.
  *
  * Usage: tsx scripts/version/publishable-range-check.ts
  */
-import { readFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { adopt_toolkits } from '#scripts/adopt/adopt-toolkits'
 import { COMMAND_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execaSync } from 'execa'
+import { peer_floor } from './peer-floor'
 import {
 	publishable_range,
 	type ProbeResult,
@@ -17,6 +21,7 @@ import {
 
 const PACKAGE_JSON_PATH = 'package.json'
 const FAILURE_EXIT_CODE = 1
+const NODE_MODULES = 'node_modules'
 
 // A registry query rather than a direct fetch: safe-chain installs shims ahead of the package
 // managers on PATH, so the answer comes back already filtered by the same minimum-age policy a
@@ -64,12 +69,44 @@ function check(package_json_content: string, probe: RangeProbe): number {
 	return report(publishable_range.find_unsatisfiable(checked, probe), checked.length)
 }
 
+/** No installed toolkit means nothing to compare against, which passes in silence. */
+function check_peer_floors(
+	package_json_content: string,
+	toolkit_json_contents: ReadonlyArray<string>,
+): number {
+	const lagging = peer_floor.find_lagging(package_json_content, toolkit_json_contents)
+
+	if (lagging.length === 0) return 0
+
+	console.error(peer_floor.format_failure(lagging))
+
+	return FAILURE_EXIT_CODE
+}
+
+// The manifest of every `@joshuafolkken/*` toolkit this project declares and has installed. The
+// roster is `josh adopt`'s own rather than a second one kept here, so a toolkit published later is
+// compared the day it is installed. kit's own checkout declares none, and a declared toolkit that is
+// not installed has no manifest to read.
+function read_installed_toolkit_manifests(project_root: string): Array<string> {
+	return adopt_toolkits
+		.all_declared_toolkits(project_root)
+		.map((package_name) => path.join(project_root, NODE_MODULES, package_name, PACKAGE_JSON_PATH))
+		.filter((manifest_path) => existsSync(manifest_path))
+		.map((manifest_path) => readFileSync(manifest_path, 'utf8'))
+}
+
+// Both checks always run, so one invocation reports everything there is to fix.
 function main(): void {
-	process.exit(check(readFileSync(PACKAGE_JSON_PATH, 'utf8'), probe_range))
+	const package_json_content = readFileSync(PACKAGE_JSON_PATH, 'utf8')
+	const range_exit_code = check(package_json_content, probe_range)
+	const toolkit_json_contents = read_installed_toolkit_manifests(process.cwd())
+	const peer_exit_code = check_peer_floors(package_json_content, toolkit_json_contents)
+
+	process.exit(Math.max(range_exit_code, peer_exit_code))
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) main()
 
-const publishable_range_check = { check }
+const publishable_range_check = { check, check_peer_floors, read_installed_toolkit_manifests }
 
 export { publishable_range_check }

package/templates/SECURITY.md

@@ -0,0 +1,23 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| Latest  | :white_check_mark: |
+| Older   | :x:                |
+
+Fixes ship in a new release rather than as patches to older versions; upgrade to the latest release to receive them. Each release's changes are listed on the [Releases](https://github.com/{{REPOSITORY}}/releases) page.
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please do not report it publicly.
+
+- **Preferred**: Open a [draft security advisory](https://github.com/{{REPOSITORY}}/security/advisories/new) on GitHub.
+- **Alternative**: If private reporting is not enabled there, contact a maintainer privately rather than opening a public issue.
+
+We aim to acknowledge reports within **48 hours** and provide a resolution or mitigation plan within **7 days** for confirmed vulnerabilities.
+
+## Development Tooling
+
+This repository takes development tooling from the [`@joshuafolkken/kit`](https://github.com/joshuafolkken/kit) package — depending on the profile it was set up with, the `josh` command, GitHub Actions workflows, Git hooks, AI agent instructions and hooks, and configuration presets. What that package ships and runs on your machine and in CI, the secrets its tooling reads, how to install safe-chain and the external MCP endpoints it configures are described in [kit's security policy](https://github.com/joshuafolkken/kit/blob/main/SECURITY.md). Report a vulnerability in that tooling to kit rather than here.

package/scripts/lint/cycle-recheck.ts

@@ -1,122 +0,0 @@
-import { FAIL_EXIT_CODE, type BufferedProcessResult } from '#scripts/lib/buffered-process'
-import type { ESLint } from 'eslint'
-
-// `import/no-cycle` reads other files, and the lint cache keys a verdict on the linted file's own
-// content. So once a cycle is closed by editing one side of it, the untouched side keeps its cached
-// `Dependency cycle detected` until its own content changes (joshuafolkken/kit#3641). The opposite
-// error cannot happen: a new cycle always contains the file that gained the import, and that file is
-// re-linted.
-//
-// A lint run therefore re-reads a cached red that names the rule: the files reported for it are
-// linted once more without the cache, and their fresh results replace the cached ones. A run that
-// reports no cycle never reaches this, so the green path costs what it did.
-//
-// That holds for a run narrowed to one change's files as much as for the whole tree: the change can
-// hold both sides of a cycle, and the side a later edit leaves alone keeps its cached report.
-//
-// The cached run is asked again through the Node API rather than read off the first run's report:
-// that report is the stylish text, and taking a file out of it means re-deriving its problem
-// counts. The second asking is answered from the cache the first one just wrote.
-const NO_CYCLE_RULE = 'import/no-cycle'
-const FORMATTER = 'stylish'
-const UNCACHED_SUFFIX = '.uncached'
-
-interface Linters {
-	cached: ESLint
-	fresh: ESLint
-}
-
-interface CycleRecheckOptions {
-	cache_file: string
-	// What the run linted — the whole tree, or one change's files — so the cached run is asked the
-	// question it was asked the first time.
-	patterns: ReadonlyArray<string>
-	// What the fixture test varies: the directory linted and the configuration it is linted with.
-	eslint_options?: ESLint.Options
-}
-
-// The exit code is eslint's "finished and reported problems", not any failure: a run that could not
-// finish — a configuration that does not load, a rule that threw — exits 2 and may name the rule
-// too, and asking it again throws the same error here, ahead of both buffered reports.
-function is_cycle_reported(result: BufferedProcessResult): boolean {
-	return result.exit_code === FAIL_EXIT_CODE && result.output.includes(NO_CYCLE_RULE)
-}
-
-function has_cycle_message(result: ESLint.LintResult): boolean {
-	return result.messages.some((message) => message.ruleId === NO_CYCLE_RULE)
-}
-
-function cached_options(options: CycleRecheckOptions): ESLint.Options {
-	return {
-		...options.eslint_options,
-		cache: true,
-		cacheStrategy: 'content',
-		cacheLocation: options.cache_file,
-	}
-}
-
-// A linter that runs without a cache deletes the cache file it would have used, and that defaults to
-// the very file the lint run keeps. So the uncached linter is pointed at a sibling path nothing
-// ever writes: the re-reading must not cost the next run its whole cache.
-function fresh_options(options: CycleRecheckOptions): ESLint.Options {
-	return {
-		...options.eslint_options,
-		cache: false,
-		cacheLocation: `${options.cache_file}${UNCACHED_SUFFIX}`,
-	}
-}
-
-// `eslint` is loaded here, only past the cycle report: it is an optional peer a basic-profile
-// consumer may not have, and this module is imported by the entry of every `josh lint`, which has to
-// reach its skip notice there.
-async function create_linters(options: CycleRecheckOptions): Promise<Linters> {
-	const eslint = await import('eslint')
-
-	return {
-		cached: new eslint.ESLint(cached_options(options)),
-		fresh: new eslint.ESLint(fresh_options(options)),
-	}
-}
-
-async function lint_fresh(
-	linter: ESLint,
-	cached: ReadonlyArray<ESLint.LintResult>,
-): Promise<Map<string, ESLint.LintResult>> {
-	const suspects = cached.filter((result) => has_cycle_message(result))
-	if (suspects.length === 0) return new Map()
-	const fresh = await linter.lintFiles(suspects.map((result) => result.filePath))
-
-	return new Map(fresh.map((result) => [result.filePath, result]))
-}
-
-async function report(
-	linter: ESLint,
-	results: Array<ESLint.LintResult>,
-): Promise<Pick<BufferedProcessResult, 'output' | 'exit_code'>> {
-	const formatter = await linter.loadFormatter(FORMATTER)
-	const is_failed = results.some((result) => result.errorCount > 0)
-
-	return { output: await formatter.format(results), exit_code: is_failed ? FAIL_EXIT_CODE : 0 }
-}
-
-async function verify(
-	result: BufferedProcessResult,
-	options: CycleRecheckOptions,
-): Promise<BufferedProcessResult> {
-	if (!is_cycle_reported(result)) return result
-	const started_at = performance.now()
-	const linters = await create_linters(options)
-	const cached = await linters.cached.lintFiles([...options.patterns])
-	const fresh = await lint_fresh(linters.fresh, cached)
-	const verified = await report(
-		linters.fresh,
-		cached.map((entry) => fresh.get(entry.filePath) ?? entry),
-	)
-
-	return { ...verified, elapsed_ms: result.elapsed_ms + performance.now() - started_at }
-}
-
-const cycle_recheck = { verify }
-
-export type { CycleRecheckOptions }
-export { cycle_recheck, NO_CYCLE_RULE }