@joshuafolkken/kit 1.872.0

package/scripts/package/package-scout-format.ts

@@ -0,0 +1,151 @@
+import {
+	package_scout,
+	type PackageMetrics,
+	type RankedTable,
+	type TierVerdict,
+} from './package-scout'
+
+// The printed shape of `josh pkg:scout` — one line per candidate with each metric labelled, then a
+// verdict line that names whether the choice is a Tier A pick or a Tier B question
+// (joshuafolkken/kit#2216). Formatting is pure so the layout and the verdict wording are unit-tested
+// without a registry.
+
+// The blank shown for a metric the registry did not report — a fact absent, never a zero measured.
+const UNKNOWN = '—'
+// The rank marker (`#1`) is padded to this width so the names after it line up.
+const RANK_WIDTH = 4
+// The column the package name is padded to, so the labelled metrics after it line up down the table.
+const NAME_WIDTH = 28
+// Score is printed to two decimals; the near-tie gap is a fraction shown as a whole-number percent.
+const SCORE_DIGITS = 2
+const PERCENT = 100
+// The number of characters an ISO timestamp carries before the time — `2025-08-01T…` → `2025-08-01`.
+const DATE_LENGTH = 10
+
+// Binary units: the registry reports `dist.unpackedSize` in bytes, and package sizes are read in KiB
+// and MiB in practice.
+const BYTE_STEP = 1024
+const SIZE_UNITS: ReadonlyArray<string> = ['B', 'KB', 'MB', 'GB']
+const SIZE_DIGITS = 1
+// Digits are grouped in threes from the right — 12345 → 12,345.
+const GROUP_SIZE = 3
+
+// Thousands grouping without Intl, so the output does not vary with the runtime's ICU data, and
+// without a look-ahead regex, whose backtracking is super-linear.
+function group_thousands(value: number): string {
+	const text = String(value)
+	const groups: Array<string> = []
+
+	for (let end = text.length; end > 0; end -= GROUP_SIZE) {
+		groups.unshift(text.slice(Math.max(0, end - GROUP_SIZE), end))
+	}
+
+	return groups.join(',')
+}
+
+function format_downloads(weekly: number | undefined): string {
+	return weekly === undefined ? UNKNOWN : `${group_thousands(weekly)}/wk`
+}
+
+function format_date(published: string | undefined): string {
+	return published === undefined ? UNKNOWN : published.slice(0, DATE_LENGTH)
+}
+
+// Step down to the largest unit the size does not overflow, capped at the last unit for anything huge.
+function scale_bytes(bytes: number): readonly [number, number] {
+	let value = bytes
+	let index = 0
+
+	while (value >= BYTE_STEP && index < SIZE_UNITS.length - 1) {
+		value /= BYTE_STEP
+		index += 1
+	}
+
+	return [value, index]
+}
+
+function format_size(bytes: number | undefined): string {
+	if (bytes === undefined) return UNKNOWN
+
+	const [value, index] = scale_bytes(bytes)
+	const digits = index === 0 ? 0 : SIZE_DIGITS
+
+	return `${value.toFixed(digits)} ${SIZE_UNITS[index] ?? 'B'}`
+}
+
+function format_row(index: number, metrics: PackageMetrics): string {
+	const name = `${metrics.name}@${metrics.version}`
+
+	return [
+		`#${String(index + 1)}`.padEnd(RANK_WIDTH),
+		name.padEnd(NAME_WIDTH),
+		`score ${metrics.score.toFixed(SCORE_DIGITS)}`,
+		`dl ${format_downloads(metrics.weekly_downloads)}`,
+		`pub ${format_date(metrics.last_publish)}`,
+		`types ${metrics.has_bundled_types ? '✓' : '✗'}`,
+		`lic ${metrics.license ?? UNKNOWN}`,
+		`size ${format_size(metrics.install_size_bytes)}`,
+	].join('  ')
+}
+
+const NO_CANDIDATES_LINE = 'Candidates: none — no package on the registry matched these keywords.'
+
+function format_percent(fraction: number): string {
+	return `${String(Math.round(fraction * PERCENT))}%`
+}
+
+// A lone candidate has nothing to be close to, so it is the pick by default — the verdict vocabulary
+// still reads `clear` so a caller keys off one word rather than counting rows.
+function format_single(metrics: PackageMetrics): string {
+	return `Tier: clear — only ${metrics.name} matched; it is the pick (Tier A).`
+}
+
+function name_or_blank(metrics: PackageMetrics | undefined): string {
+	return metrics?.name ?? ''
+}
+
+function lead_line(table: RankedTable): string {
+	const [first, second] = table.ranked
+	const names = `${name_or_blank(first)} leads ${name_or_blank(second)}`
+
+	return `${names} by ${format_percent(table.gap ?? 0)}`
+}
+
+function format_pair(table: RankedTable, verdict: TierVerdict): string {
+	const threshold = format_percent(package_scout.NEAR_TIE_THRESHOLD)
+	const lead = lead_line(table)
+
+	if (verdict === 'clear') return `Tier: clear — ${lead} (≥ ${threshold}); select it (Tier A).`
+
+	return `Tier: close — ${lead} (< ${threshold}); ask the user (Tier B).`
+}
+
+function format_verdict(table: RankedTable): string {
+	const [first] = table.ranked
+
+	if (first === undefined) return NO_CANDIDATES_LINE
+	if (table.verdict === undefined) return format_single(first)
+
+	return format_pair(table, table.verdict)
+}
+
+function format_table(table: RankedTable): string {
+	if (table.ranked.length === 0) return NO_CANDIDATES_LINE
+
+	const rows = table.ranked.map((metrics, index) => format_row(index, metrics))
+
+	return [...rows, '', format_verdict(table)].join('\n')
+}
+
+const package_scout_format = {
+	NO_CANDIDATES_LINE,
+	group_thousands,
+	format_downloads,
+	format_date,
+	format_size,
+	format_row,
+	format_verdict,
+	format_table,
+}
+
+export { package_scout_format }

package/scripts/package/package-scout.ts

@@ -0,0 +1,121 @@
+// The measured metrics behind `josh pkg:scout` — the ranking of package candidates and the near-tie
+// verdict that turns the Package-First "clearly best (Tier A) / genuine toss-up (Tier B)" branch from
+// an impression into a computed answer (joshuafolkken/kit#2216).
+//
+// This module is the pure half: it takes candidates already gathered from the npm registry and
+// answers two things — the order they rank in, and whether the top two are close enough that the
+// choice is a Tier B question rather than a Tier A pick. The network reads live in
+// `package-scout-cli.ts`, so the transform and the boundary are unit-tested without a registry.
+
+// The relative lead below which the top two candidates are a near-tie. The registry's `score.final`
+// is a relevance-weighted number of no fixed scale, so the gap is read as a fraction of the leader's
+// score — `(top − second) / top` — rather than as an absolute difference. A leader ahead by less than
+// this fraction is inside the noise, so the choice is the user's (Tier B) rather than the run's.
+const NEAR_TIE_THRESHOLD = 0.15
+
+// One candidate's registry facts, gathered per package: the version metadata (bundled types, license,
+// unpacked size) that the search listing does not carry. Every field present, some absent as
+// `undefined` — a fact the registry did not report is a blank in the row, never a scan that failed.
+interface RegistryFacts {
+	has_bundled_types: boolean
+	license: string | undefined
+	install_size_bytes: number | undefined
+}
+
+// A candidate as the search listing reports it: its name, the version searched, npm's composite score
+// (the ranking key), and the version's publish date. The score is what the near-tie verdict reads.
+interface SearchCandidate {
+	name: string
+	version: string
+	score: number
+	last_publish: string | undefined
+}
+
+// A candidate with every measured metric folded together, one row of the ranking table.
+interface PackageMetrics {
+	name: string
+	version: string
+	// npm's composite score (quality + popularity + maintenance), the ranking key.
+	score: number
+	weekly_downloads: number | undefined
+	last_publish: string | undefined
+	has_bundled_types: boolean
+	license: string | undefined
+	install_size_bytes: number | undefined
+}
+
+// `clear` — the top candidate leads by more than the near-tie threshold, so it is the Tier A pick.
+// `close` — the top two are within it, so the choice is a Tier B question for the user.
+type TierVerdict = 'clear' | 'close'
+
+interface RankedTable {
+	ranked: ReadonlyArray<PackageMetrics>
+	// The relative lead of the top two, undefined when fewer than two candidates ranked.
+	gap: number | undefined
+	// The verdict, undefined when there is nothing to compare (0 or 1 candidate).
+	verdict: TierVerdict | undefined
+}
+
+// The search listing and the per-package facts, folded into one row. The two are gathered from
+// separate registry reads, so a candidate whose facts read failed still ranks on its search score.
+function to_metrics(
+	candidate: SearchCandidate,
+	facts: RegistryFacts,
+	weekly_downloads: number | undefined,
+): PackageMetrics {
+	return {
+		name: candidate.name,
+		version: candidate.version,
+		score: candidate.score,
+		last_publish: candidate.last_publish,
+		has_bundled_types: facts.has_bundled_types,
+		license: facts.license,
+		install_size_bytes: facts.install_size_bytes,
+		weekly_downloads,
+	}
+}
+
+// Strongest first. Ties keep input order, which reads less arbitrarily than an unstable sort — and an
+// equal score is exactly the near-tie the verdict then reports rather than something the order hides.
+function rank(candidates: ReadonlyArray<PackageMetrics>): Array<PackageMetrics> {
+	return [...candidates].toSorted((left, right) => right.score - left.score)
+}
+
+// The lead of the top candidate over the next as a fraction of the leader's score, or undefined when
+// there is no pair to compare. Scaled by the leader so the threshold holds whatever the score's range:
+// a leader whose score is zero has no lead over an equal runner-up, so the gap is zero (a near-tie).
+function tie_gap(ranked: ReadonlyArray<PackageMetrics>): number | undefined {
+	const [first, second] = ranked
+
+	if (first === undefined || second === undefined) return undefined
+	if (first.score <= 0) return 0
+
+	return (first.score - second.score) / first.score
+}
+
+function verdict_of(gap: number | undefined): TierVerdict | undefined {
+	if (gap === undefined) return undefined
+
+	return gap < NEAR_TIE_THRESHOLD ? 'close' : 'clear'
+}
+
+// The whole answer: the candidates in order, the top-two gap, and whether that gap makes the choice a
+// Tier A pick or a Tier B question.
+function build_table(candidates: ReadonlyArray<PackageMetrics>): RankedTable {
+	const ranked = rank(candidates)
+	const gap = tie_gap(ranked)
+
+	return { ranked, gap, verdict: verdict_of(gap) }
+}
+
+const package_scout = {
+	NEAR_TIE_THRESHOLD,
+	to_metrics,
+	rank,
+	tie_gap,
+	verdict_of,
+	build_table,
+}
+
+export type { PackageMetrics, RankedTable, RegistryFacts, SearchCandidate, TierVerdict }
+export { package_scout }

package/scripts/ports/port-command.ts

@@ -0,0 +1,87 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { ports, type PortEnvironment } from '#ports'
+
+const SUCCESS_EXIT_CODE = 0
+const USAGE_EXIT_CODE = 1
+const FAILURE_EXIT_CODE = 1
+const EXPECTED_ARGUMENT_COUNT = 1
+const ARGV_OFFSET = 2
+
+type PortName = 'dev' | 'preview'
+
+interface PortResult {
+	text: string
+	exit_code: number
+}
+
+const RESOLVERS: Record<PortName, (environment?: PortEnvironment) => number> = {
+	dev: ports.resolve_development_port,
+	preview: ports.resolve_preview_port,
+}
+
+const PORT_NAMES: ReadonlyArray<string> = Object.keys(RESOLVERS)
+const USAGE = `Usage: josh port <${PORT_NAMES.join('|')}>`
+
+function is_port_name(value: string | undefined): value is PortName {
+	return value !== undefined && Object.hasOwn(RESOLVERS, value)
+}
+
+// Shell contexts cannot import the resolver, so `$(josh port preview)` is how a package.json
+// script stays on kit's single port definition instead of re-deriving the arithmetic. The output is
+// substituted straight into a command line, so success prints the number and nothing else; anything
+// else would corrupt the port argument it feeds. The documented form calls the binary rather than
+// `pnpm josh`, because a `pnpm run` wrapper writes its own `[ELIFECYCLE]` line and any install log
+// to that same stream and nothing here can suppress them (#825).
+function run(argv: ReadonlyArray<string>, environment?: PortEnvironment): PortResult {
+	const [name] = argv
+
+	// An extra argument is refused rather than ignored: `josh port dev preview` printing the dev
+	// port would feed a silently wrong number into the command line that substitutes it.
+	if (argv.length !== EXPECTED_ARGUMENT_COUNT || !is_port_name(name)) {
+		return { text: USAGE, exit_code: USAGE_EXIT_CODE }
+	}
+
+	// An invalid `PORT_SEED` throws out of the resolver. Reporting the message alone keeps the
+	// failure readable in the terminal that ran `pnpm preview`, where a raw stack trace would bury
+	// the one line saying which variable to fix.
+	try {
+		return { text: String(RESOLVERS[name](environment)), exit_code: SUCCESS_EXIT_CODE }
+	} catch (error) {
+		return {
+			text: error instanceof Error ? error.message : String(error),
+			exit_code: FAILURE_EXIT_CODE,
+		}
+	}
+}
+
+// #826: the resolver finds `.env` at the project root, where `pnpm run` starts the scripts that
+// substitute this command's output. It replaces the `--env-file-if-exists=.env` tsx flag this
+// command used to carry, which resolved relative to the working directory instead — so running the
+// command from a subdirectory answered with the unseeded port while `playwright.config.ts`, which
+// already uses this resolver, answered with the seeded one. One reader, one file.
+function main(argv: ReadonlyArray<string>): void {
+	ports.load_environment_file()
+
+	const { text, exit_code } = run(argv)
+
+	if (exit_code === SUCCESS_EXIT_CODE) {
+		console.info(text)
+
+		return
+	}
+
+	console.error(text)
+	process.exit(exit_code)
+}
+
+const port_command = {
+	is_port_name,
+	run,
+	PORT_NAMES,
+	USAGE,
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(ARGV_OFFSET))
+
+export { port_command }

package/scripts/propagate/propagate-git-failure.ts

@@ -0,0 +1,191 @@
+import { propagate_git } from './propagate-git'
+import type { StepResult } from './propagate-run'
+
+// Where `josh git` actually stopped inside a consumer, and what it left there.
+//
+// `josh git` is three things under one command — stage and commit, push, open the pull request — and
+// a failed spawn reports one exit code for all three. The run's report then appended "upgrade/sync
+// changes left uncommitted" to that code, which names the *first* of the three: so a consumer whose
+// pre-push hook refused the push was reported as a consumer whose sync never got committed, and the
+// reader went looking at a sync that had worked (joshuafolkken/kit#1417).
+//
+// **Nothing here changes whether a push is blocked.** A consumer's pre-push gate refusing a push is
+// the gate doing its job, and the probes below are read-only. What is fixed is the sentence.
+
+// The last lines of `josh git`'s own output are what name the check that stopped it: a pre-push hook
+// prints its steps as it runs them and ends on the one that failed, and git's refusal follows. Three
+// lines carry that pair without breaking the report's one-line-per-consumer shape.
+const TAIL_LINE_COUNT = 3
+const TAIL_SEPARATOR = ' / '
+// eslint-disable-next-line no-control-regex -- the escape sequences to strip are control characters
+const ANSI_PATTERN = /\[[0-9;?]*[ -/]*[@-~]/gu
+const LINE_BREAK_PATTERN = /[\r\n]/u
+const TAIL_LABEL = 'last output: '
+const NO_COMMIT = 'nothing was committed'
+const NOT_OPENED = 'the branch reached origin, but the pull request was not opened'
+const HOOK_REFUSED = "but the consumer's pre-push hook refused the push"
+const PUSH_FAILED = 'but the push did not reach origin'
+const NOTHING_LEFT = 'nothing was left behind'
+const LEFTOVER_LABEL = 'left behind: '
+const LEFTOVER_JOIN = ' and '
+const UNCOMMITTED = 'uncommitted changes'
+
+// The facts one classification is made from, gathered once so the decision itself stays pure and
+// testable without a repository.
+interface GitStepState {
+	// The feature branch `josh git` created, or nothing when the checkout is still on its default
+	// branch — which is what a failure before the branch existed looks like. Written as "present,
+	// possibly undefined" rather than optional: `exactOptionalPropertyTypes` is on and the probes
+	// below answer `undefined` rather than omitting the key, which is the same reason
+	// `git-fixture-workspace.ts` declares `restore_environment` this way.
+	branch: string | undefined
+	// The commit that branch carries beyond the default branch, or nothing when it carries none.
+	head_commit: string | undefined
+	is_tree_clean: boolean
+	is_on_remote: boolean
+	is_push_hook_blocked: boolean
+}
+
+// The remote half of the state, kept apart because it is the half that costs network round trips.
+interface PushState {
+	is_on_remote: boolean
+	is_push_hook_blocked: boolean
+}
+
+const NOT_PUSHED: PushState = { is_on_remote: false, is_push_hook_blocked: false }
+
+function push_reason(state: GitStepState): string {
+	return state.is_push_hook_blocked ? HOOK_REFUSED : PUSH_FAILED
+}
+
+// Which of `josh git`'s three sub-steps stopped, read from what the consumer's repository holds now.
+function describe_failure(state: GitStepState): string {
+	const { branch, head_commit } = state
+	if (branch === undefined || head_commit === undefined) return NO_COMMIT
+	if (state.is_on_remote) return NOT_OPENED
+
+	return `committed ${head_commit} on ${branch}, ${push_reason(state)}`
+}
+
+// The last lines of one stream. Split on carriage returns as well as newlines, because a push's
+// progress meter and pnpm's spinners overwrite one line with `\r` — counted as a single line, one of
+// them alone would fill a tail slot with kilobytes. Escape sequences go for the same reason: this
+// text lands in a report that is one line per consumer.
+function stream_tail(text: string): string {
+	return text
+		.replaceAll(ANSI_PATTERN, '')
+		.split(LINE_BREAK_PATTERN)
+		.map((line) => line.trim())
+		.filter((line) => line !== '')
+		.slice(-TAIL_LINE_COUNT)
+		.join(TAIL_SEPARATOR)
+}
+
+// `josh git`'s own last lines, folded onto one. It is the *last* lines that matter, because a hook
+// that stops mid-run ends on the check that stopped it — the one fact nothing else in the run keeps.
+//
+// **Each stream is tailed separately**, and that is not tidiness: git writes its refusal to stderr
+// while a hook's own progress commonly goes to stdout, so a tail taken across the two concatenated
+// would be all stderr whenever stderr had enough lines — dropping exactly the hook output this
+// exists to carry. A synchronous spawn cannot interleave them, so neither is allowed to crowd the
+// other out.
+function output_tail(streams: ReadonlyArray<string>): string {
+	const tails = streams.map((text) => stream_tail(text)).filter((tail) => tail !== '')
+
+	if (tails.length === 0) return ''
+
+	return ` — ${TAIL_LABEL}${tails.join(TAIL_SEPARATOR)}`
+}
+
+// What the failure left in the consumer, read from the tree rather than from which step ran. A
+// `josh git` that got as far as committing left no uncommitted changes at all, so the standing note
+// — the one saying the upgrade and the sync are still sitting there uncommitted — is false exactly
+// where this module is reached.
+function leftover_note(state: GitStepState): string {
+	const parts: Array<string> = []
+
+	if (!state.is_tree_clean) parts.push(UNCOMMITTED)
+	if (state.branch !== undefined) parts.push(`the branch ${state.branch}`)
+	if (parts.length === 0) return NOTHING_LEFT
+
+	return `${LEFTOVER_LABEL}${parts.join(LEFTOVER_JOIN)}`
+}
+
+// The branch `josh git` created, or nothing when the checkout never left its default branch.
+function feature_branch(repository_path: string, default_name: string): string | undefined {
+	const branch = propagate_git.current_branch(repository_path)
+
+	return branch === undefined || branch === default_name ? undefined : branch
+}
+
+// Asked only where there is a commit that could have been pushed. A branch carrying no commit of its
+// own was never pushed, and asking anyway would spend two network round trips on a question the
+// classification above never reaches.
+function read_push_state(
+	repository_path: string,
+	branch: string | undefined,
+	head_commit: string | undefined,
+): PushState {
+	if (branch === undefined || head_commit === undefined) return NOT_PUSHED
+
+	if (propagate_git.has_remote_branch(repository_path, branch)) {
+		return { is_on_remote: true, is_push_hook_blocked: false }
+	}
+
+	// The real push has already failed by the time this runs — that is what made the step fail — so a
+	// dry run that goes through with the hooks out of the way says the hook is what stopped it. The
+	// hook has to exist for that to follow, and the local check is asked first so a consumer with no
+	// hook costs no round trip at all.
+	return {
+		is_on_remote: false,
+		is_push_hook_blocked:
+			propagate_git.has_pre_push_hook(repository_path) &&
+			propagate_git.can_push_without_hooks(repository_path, branch),
+	}
+}
+
+function read_state(repository_path: string): GitStepState {
+	const default_name = propagate_git.default_branch(repository_path)
+	const branch = feature_branch(repository_path, default_name)
+	const head_commit =
+		branch === undefined ? undefined : propagate_git.commit_ahead(repository_path, default_name)
+
+	return {
+		branch,
+		head_commit,
+		is_tree_clean: propagate_git.is_clean(repository_path),
+		...read_push_state(repository_path, branch, head_commit),
+	}
+}
+
+// Replace `josh git`'s bare exit code with the sub-step that produced it, and record what that
+// failure left in the consumer. Both are probed from the consumer's own repository, because the exit
+// code is the same one whichever of the three sub-steps stopped.
+function attribute(
+	repository_path: string,
+	result: StepResult,
+	streams: ReadonlyArray<string>,
+): StepResult {
+	const state = read_state(repository_path)
+	const detail = `${result.detail ?? 'failed'} — ${describe_failure(state)}${output_tail(streams)}`
+
+	return { ...result, detail, leftover: leftover_note(state) }
+}
+
+const propagate_git_failure = {
+	HOOK_REFUSED,
+	NOTHING_LEFT,
+	NO_COMMIT,
+	NOT_OPENED,
+	PUSH_FAILED,
+	TAIL_LINE_COUNT,
+	UNCOMMITTED,
+	attribute,
+	describe_failure,
+	leftover_note,
+	output_tail,
+	read_state,
+}
+
+export type { GitStepState }
+export { propagate_git_failure }