@joshuafolkken/kit 1.1373.0 → 1.1383.0

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/backlog/backlog-idle.ts

@@ -1,88 +0,0 @@
-import { backlog_budget, type BudgetInput } from './backlog-budget'
-
-// The idle watch as a window a person can read: when the run began waiting on
-// an empty backlog, when the wait ends, and which bound ends it. Without it the moment the wait began
-// would live only in `backlog:drive`'s memory as `--active`, so a reader of the event stream could
-// tell the run was waiting but not until when. The budget names the
-// window, `backlog:offer` records it as an `idle` event, and `run:board` reads it back — all through the
-// text written and parsed here, so the three never spell it differently.
-
-type IdleBound = 'idle' | 'whole-run'
-
-interface IdleWindow {
-	since_ms: number
-	until_ms: number
-	// Which bound ends the wait: the idle budget running out, or the whole-run bound arriving first.
-	bound: IdleBound
-	// When the watching loop last asked the backlog — the poll the next one is counted from.
-	asked_ms: number
-}
-
-const TEXT_PATTERN =
-	/^idle since (?<since>\S+) until (?<until>\S+) \((?<bound>idle|whole-run)\) asked (?<asked>\S+)$/u
-const IDLE_BOUND: IdleBound = 'idle'
-const WHOLE_RUN_BOUND: IdleBound = 'whole-run'
-
-// The window an idle watch opened at `active_at_ms` runs for, as asked at `now_ms`, or `undefined` when
-// the watch is off. The wait ends at the earlier of the idle budget and the whole-run bound — the order
-// `decide` applies.
-function window_of(input: BudgetInput): IdleWindow | undefined {
-	if (input.idle_budget_ms === undefined) return undefined
-
-	const idle_until = input.active_at_ms + input.idle_budget_ms
-	const run_until = input.started_at_ms + backlog_budget.WHOLE_RUN_BUDGET_MS
-	const bound = run_until < idle_until ? WHOLE_RUN_BOUND : IDLE_BOUND
-
-	return {
-		since_ms: input.active_at_ms,
-		until_ms: Math.min(idle_until, run_until),
-		bound,
-		asked_ms: input.now_ms,
-	}
-}
-
-function iso_of(ms: number): string {
-	return new Date(ms).toISOString()
-}
-
-function text_of(window: IdleWindow): string {
-	const { since_ms, until_ms, bound, asked_ms } = window
-
-	return `idle since ${iso_of(since_ms)} until ${iso_of(until_ms)} (${bound}) asked ${iso_of(asked_ms)}`
-}
-
-function is_bound(value: string | undefined): value is IdleBound {
-	return value === IDLE_BOUND || value === WHOLE_RUN_BOUND
-}
-
-// A malformed stamp reads as no window rather than as `NaN`, so a mangled line is never drawn.
-function window_from(groups: Record<string, string>, bound: IdleBound): IdleWindow | undefined {
-	const since_ms = Date.parse(String(groups['since']))
-	const until_ms = Date.parse(String(groups['until']))
-	const asked_ms = Date.parse(String(groups['asked']))
-
-	return Number.isNaN(since_ms + until_ms + asked_ms)
-		? undefined
-		: { since_ms, until_ms, bound, asked_ms }
-}
-
-function parse(text: string): IdleWindow | undefined {
-	const groups = TEXT_PATTERN.exec(text)?.groups
-
-	if (groups === undefined || !is_bound(groups['bound'])) return undefined
-
-	return window_from(groups, groups['bound'])
-}
-
-// The next time the watching loop asks the backlog again: one `IDLE_POLL_MINUTES` after the ask the
-// stream recorded, never past the end of the wait — the interval `idle_watch_reason` tells the loop.
-function next_check_ms(window: IdleWindow): number {
-	const poll_ms = backlog_budget.IDLE_POLL_MINUTES * backlog_budget.MS_PER_MINUTE
-
-	return Math.min(window.asked_ms + poll_ms, window.until_ms)
-}
-
-const backlog_idle = { next_check_ms, parse, text_of, window_of }
-
-export { backlog_idle }
-export type { IdleBound, IdleWindow }