@joshuafolkken/kit 1.1373.0 → 1.1379.0

package/scripts/josh/josh-commands-versioning.ts

@@ -20,7 +20,8 @@ const VERSIONING_COMMANDS: Record<string, CommandEntry> = {
 	// before chaining here, exactly as it already does for `latest:update`.
 	ranges: {
 		script: 'scripts/version/publishable-range-check.ts',
-		description: 'Check that every published dependency range still resolves for a consumer',
+		description:
+			'Check that every published dependency range still resolves for a consumer and no peer range falls below an installed toolkit',
 		category: 'Versioning',
 		reference: ['', 'developer', ['network']],
 	},

package/scripts/propagate/propagate-run.ts

@@ -13,6 +13,7 @@ import type { PropagateTarget } from './propagate-targets'
 const STEP_PRECHECK = 'working tree check'
 const STEP_UPGRADE = 'josh vu'
 const STEP_SYNC = 'josh sync'
+const STEP_LATEST = 'josh latest'
 const STEP_LINT_RELATED = 'related lint check'
 const STEP_TEST_RELATED = 'related test check'
 const STEP_VERIFY = 'verification gate'
@@ -32,6 +33,18 @@ const STEP_ORDER: ReadonlyArray<string> = [
 	STEP_PR,
 	STEP_RETURN,
 ]
+// The same sequence with the consumer's other dependencies, its audit and its pnpm pin brought up
+// to date after the sync. Only `josh adopt` runs it: `josh latest` moves every dependency to the
+// registry's newest, which is what adoption is for and exactly what propagation's exact-version wait
+// exists to prevent — and an unrelated dependency's breakage would stop a release reaching a
+// consumer. Derived from `STEP_ORDER` rather than listed, so the two cannot drift apart; behind the
+// sync, because the sync can add devDependencies to `package.json` without installing them, and a
+// pull request opened over that fails CI's frozen install — the step installs before it updates
+// (`propagate_steps`), so the lockfile is re-resolved even when `josh latest` rolls its update back.
+// The related checks and the gate that follow then verify the tree as it will be committed.
+const ADOPT_STEP_ORDER: ReadonlyArray<string> = STEP_ORDER.flatMap((step) =>
+	step === STEP_SYNC ? [step, STEP_LATEST] : step,
+)
 const PROPAGATED_REASON = 'opened a pull request'
 
 type RunOutcome = 'propagated' | 'failed' | 'skipped'
@@ -130,10 +143,11 @@ function run_target(
 	target: PropagateTarget,
 	run_step: RunStep,
 	success_reason: string = PROPAGATED_REASON,
+	order: ReadonlyArray<string> = STEP_ORDER,
 ): TargetResult {
 	const steps: Array<StepResult> = []
 
-	for (const step of STEP_ORDER) {
+	for (const step of order) {
 		const result = run_step(target, step)
 
 		steps.push(result)
@@ -192,11 +206,13 @@ const propagate_run = {
 	STEP_ISSUE,
 	STEP_UPGRADE,
 	STEP_SYNC,
+	STEP_LATEST,
 	STEP_LINT_RELATED,
 	STEP_TEST_RELATED,
 	STEP_VERIFY,
 	STEP_PR,
 	STEP_ORDER,
+	ADOPT_STEP_ORDER,
 	skip_reason,
 	run_target,
 	run_targets,

package/scripts/propagate/propagate-steps.ts

@@ -27,10 +27,17 @@ const SUCCESS_EXIT_CODE = 0
 // pass — so the chain is not repeated here. It resolves in the consumer's directory, which by this
 // point has already been upgraded to the version being propagated, so the command is present.
 const VERIFY_SCRIPT = `pnpm josh ${GATE_COMMAND}`
+// `josh latest` behind an install of its own. The sync can add devDependencies to `package.json`
+// without installing them, and `josh latest` does not always re-resolve the lockfile: when the age
+// gate would downgrade a dependency it restores the files it found and exits zero. Installing first
+// makes the tree it finds a consistent one, so the lockfile matches `package.json` on either path.
+// `--no-frozen-lockfile` because the install exists to write the lockfile, which pnpm refuses under CI.
+const LATEST_SCRIPT = 'pnpm install --no-frozen-lockfile && pnpm josh latest'
 
 // The commands the release-independent spawning steps run inside the target's own directory. The
 // upgrade and the sync are not here: both are per toolkit, so they are built from the plan instead.
 const STEP_COMMANDS: Readonly<Record<string, ReadonlyArray<string>>> = {
+	[propagate_run.STEP_LATEST]: ['sh', '-c', LATEST_SCRIPT],
 	[propagate_run.STEP_LINT_RELATED]: ['pnpm', 'josh', 'lint:related'],
 	[propagate_run.STEP_TEST_RELATED]: ['pnpm', 'josh', 'test:related'],
 	[propagate_run.STEP_VERIFY]: ['sh', '-c', VERIFY_SCRIPT],
@@ -353,7 +360,8 @@ interface Release {
 // `josh propagate` always passes exactly one release; `josh adopt` passes every toolkit installed in
 // the repository it runs in. Only the upgrade and the sync repeat per
 // release — the pre-check, the verification gate, the issue, the pull request and the return to the
-// default branch happen once, which is why the step order itself is unchanged.
+// default branch happen once, which is why the step order does not depend on the plan — `josh adopt`
+// runs `propagate_run.ADOPT_STEP_ORDER`, the same order with `josh latest` added.
 interface ReleasePlan {
 	releases: ReadonlyArray<Release>
 	origin: string

package/scripts/sync/sync-ai-files.ts

@@ -5,6 +5,7 @@ import { transform_copied_content } from '#scripts/init/init-copy-content'
 import { init_logic } from '#scripts/init/init-logic'
 import { PACKAGE_DIR, PROJECT_ROOT } from '#scripts/init/init-paths'
 import type { ProjectShape } from '#scripts/init/project-profile'
+import { security_policy } from '#scripts/init/security-policy'
 import { file_reader } from '#scripts/lib/read-file'
 import { pack_hook } from '#scripts/safe-chain/pack-hook'
 import { copy_directory_failure, directory_copy_blocker } from './directory-copy-guard'
@@ -80,6 +81,7 @@ function sync_workspace_yaml(
 
 // The source is the profile's: a basic project syncs from its own templates, as `josh init` wrote it.
 function sync_ai_copy_file(filename: string, is_force: boolean, shape?: ProjectShape): void {
+	if (security_policy.did_skip_unresolved(filename, PROJECT_ROOT)) return
 	const source = init_ai_copy.ai_file_source(filename, shape)
 
 	if (filename === WORKSPACE_YAML) {

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.