@joshuafolkken/kit 1.872.0

package/scripts/run/run-watcher-guard.ts

@@ -0,0 +1,59 @@
+import { lane_registry } from '#scripts/lane/lane-registry'
+import { run_progress_clock } from './run-progress-clock'
+
+// A watcher that stopped while children are still in-flight leaves the parent blind to completions
+// for up to the full heartbeat interval. This guard detects that state so a hook can refuse the
+// calls that follow a missed restart (joshuafolkken/kit#2113).
+//
+// **Staleness threshold is `TICK_MULTIPLIER` watcher ticks.** The watcher pings its life record on
+// every tick (every 30 s), so a gap wider than three ticks means the process has almost certainly
+// stopped: either the bound expired or the session was cut without a restart. Three gives one missed
+// tick of slack before the guard fires.
+//
+// **It watches no relay** (joshuafolkken/kit#2492). A session following the run's event stream after a
+// cut used to be held to it here; that relay re-read the session's whole history per event, so the
+// stream is now watched from a pane of its own (`run:event --watch`) and no session owes it.
+
+const WATCHER_TICK_MS = 30_000
+const TICK_MULTIPLIER = 3
+const MS_PER_SECOND = 1000
+
+const STALE_THRESHOLD_MS = WATCHER_TICK_MS * TICK_MULTIPLIER
+const STALE_THRESHOLD_S = STALE_THRESHOLD_MS / MS_PER_SECOND
+
+const STALE_NOTE =
+	`Lane children are in-flight but the progress watcher has not pinged in the last ` +
+	`${String(STALE_THRESHOLD_S)}s — run \`pnpm josh run:progress --wait\` in the background before proceeding`
+
+type GuardResult = { kind: 'ok' } | { kind: 'stale'; note: string }
+
+const OK_RESULT: GuardResult = { kind: 'ok' }
+
+// The lanes a parent is still waiting on. A stranded lane has no child working in it, so it is not
+// in-flight — the one definition both this guard and the headless stop rule read (`run-headless.ts`).
+async function has_lanes_in_flight(): Promise<boolean> {
+	const all_lanes = await lane_registry.list_lanes()
+
+	return all_lanes.some((lane) => !lane.is_stranded)
+}
+
+// `life_target` is the path returned by `run_progress_read.stamp_target()` or
+// `run_progress_clock.life_target_of(git_directory)`. Passed in rather than resolved here so the
+// caller can use whichever resolution fits its sync/async context.
+async function check(life_target: string): Promise<GuardResult> {
+	if (!(await has_lanes_in_flight())) return OK_RESULT
+
+	if (run_progress_clock.is_life_fresh(life_target, STALE_THRESHOLD_MS)) return OK_RESULT
+
+	return { kind: 'stale', note: STALE_NOTE }
+}
+
+const run_watcher_guard = {
+	STALE_NOTE,
+	STALE_THRESHOLD_MS,
+	check,
+	has_lanes_in_flight,
+}
+
+export type { GuardResult }
+export { run_watcher_guard }

package/scripts/run/run-watcher-hook.ts

@@ -0,0 +1,86 @@
+import { hook_decision } from '#scripts/josh/hook-decision'
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { z } from 'zod'
+import { run_progress_read } from './run-progress-read'
+import { run_watcher_guard } from './run-watcher-guard'
+
+// The `PreToolUse` adapter that turns `run_watcher_guard`'s verdict into a deny reason, so the guard
+// the CLI already carries is finally *called* on every tool call rather than left to prose asking the
+// run to call it (joshuafolkken/kit#2353). It is composed into `pretool-guard.ts` — the one PreToolUse
+// hook, kept one by joshuafolkken/kit#1930 — rather than added as a second `.claude/settings.json`
+// entry, so the consolidation invariant holds; the detection itself is unchanged.
+//
+// **It fires once per run, for the same reason every guard here stamps.** A stale watcher would other-
+// wise refuse *every* tool call, including the `pnpm josh run:progress --wait` that fixes it — a wedge.
+// So the first stale call is refused and that refusal is recorded; the next call, the restart, is
+// allowed. Restarting the watcher pings its life record fresh, so the guard falls silent on its own.
+//
+// **A dispatched lane child is exempt.** Only the outermost run keeps a watcher (`run-progress-cli.ts`),
+// so a child carrying `JOSH_LANE_CHILD` must not be refused for a watcher it was never meant to start.
+
+const SWITCH_ENV_KEY = 'JOSH_WATCHER_GUARD'
+const STAMP_PREFIX = 'josh-watcher-guard-'
+
+const payload_schema = z.object({ transcript_path: z.string().min(1) })
+
+function transcript_of(raw_payload: string): string | undefined {
+	try {
+		const parsed = payload_schema.safeParse(JSON.parse(raw_payload))
+
+		return parsed.success ? parsed.data.transcript_path : undefined
+	} catch {
+		return undefined
+	}
+}
+
+// The once-per-run arm: refuse only when nothing has been recorded yet, and record before returning so
+// the refusal cannot repeat on the call in hand. A record that cannot be written allows the call — the
+// fail-open direction the transcript guards take for the same reason.
+function fires_once(transcript: string, now_ms: number): boolean {
+	const stamp = hook_decision.create_refusal_stamp(STAMP_PREFIX)
+	const target = stamp.path(transcript)
+
+	if (stamp.last_ms(target) !== hook_decision.NEVER_MS) return false
+
+	return stamp.record(target, now_ms)
+}
+
+// The guard is off when its switch is disabled or when this session is a dispatched lane child, which
+// runs no watcher of its own.
+function is_active(): boolean {
+	return (
+		hook_decision.is_switch_enabled(SWITCH_ENV_KEY) &&
+		lane_child_marker.marked_issue() === undefined
+	)
+}
+
+// The guard's note when the watcher is stale and this call is the once-per-run one that refuses, or
+// `undefined` when the watcher is fresh (or the refusal was already spent this run). No session is asked
+// to relay the run's stream any more — the watch pane does (joshuafolkken/kit#2492).
+async function stale_reason(transcript: string, now_ms: number): Promise<string | undefined> {
+	const result = await run_watcher_guard.check(await run_progress_read.live_target())
+
+	if (result.kind === 'ok') return undefined
+
+	return fires_once(transcript, now_ms) ? result.note : undefined
+}
+
+// The deny reason for a tool call that arrives while lane children are in-flight and the watcher has
+// gone stale, or `undefined` when the call proceeds. Async because the lane listing and the life
+// record are read from disk; the composing hook already awaits.
+async function watcher_hook_reason(
+	raw_payload: string,
+	now_ms: number = Date.now(),
+): Promise<string | undefined> {
+	if (!is_active()) return undefined
+
+	const transcript = transcript_of(raw_payload)
+
+	if (transcript === undefined) return undefined
+
+	return await stale_reason(transcript, now_ms)
+}
+
+const run_watcher_hook = { SWITCH_ENV_KEY, STAMP_PREFIX, watcher_hook_reason }
+
+export { run_watcher_hook }

package/scripts/security/secretlint-scan.ts

@@ -0,0 +1,86 @@
+#!/usr/bin/env tsx
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { resolve_local_bin } from '#scripts/build/local-bin'
+import { resolve_spawn_exit } from '#scripts/lib/spawn-exit'
+import { execaSync } from 'execa'
+
+const SECRETLINT_BIN = 'secretlint'
+const NO_GLOB_FLAG = '--no-glob'
+const ARGV_OFFSET = 2
+
+// The scan is defense in depth ahead of GitHub push protection, not the only gate, so a
+// missing binary must not block the commit. kit ships the pre-commit rule inside
+// lefthook/base.yml, but secretlint itself resolves from the consumer project — `josh init`
+// and `josh sync` add it to the consumer devDependencies, because pnpm's isolated layout
+// never exposes a kit dependency's bin to the consumer's `pnpm exec`. Upgrading kit therefore
+// activates this hook one `josh sync` + `pnpm install` ahead of the binary, and a bare
+// `pnpm exec secretlint` turns that window into a hard failure on every commit (kit#695).
+const MISSING_NOTICE =
+	`⚠️  secretlint is not installed — skipping the staged-file secret scan.\n` +
+	`   The kit pre-commit hook ships ahead of the dependency it needs.\n` +
+	`   Run \`pnpm josh sync && pnpm install\` to provision it.`
+
+type ScanDecision = { kind: 'skip'; notice?: string } | { kind: 'scan'; binary: string }
+
+function resolve_secretlint_binary(project_root: string): string | undefined {
+	const candidate = resolve_local_bin(project_root, SECRETLINT_BIN)
+
+	return existsSync(candidate) ? candidate : undefined
+}
+
+// lefthook substitutes literal paths, so `--no-glob` is mandatory: a SvelteKit route directory
+// such as `(app)` or `[id]` would otherwise reach secretlint's glob engine as a pattern.
+// Masking and the .gitignore cascade are both on by default in v13 — no flag adds them.
+function build_scan_arguments(staged_files: ReadonlyArray<string>): Array<string> {
+	return [NO_GLOB_FLAG, ...staged_files]
+}
+
+function plan_scan(staged_files: ReadonlyArray<string>, project_root: string): ScanDecision {
+	if (staged_files.length === 0) return { kind: 'skip' }
+
+	const binary = resolve_secretlint_binary(project_root)
+
+	if (binary === undefined) return { kind: 'skip', notice: MISSING_NOTICE }
+
+	return { kind: 'scan', binary }
+}
+
+// No `shell` option on purpose. execa resolves a Windows `.cmd` shim itself and escapes the
+// arguments for cmd.exe's double expansion; turning the shell on would bypass that and let a
+// staged path containing a space split into two paths — the scanner would then quietly walk
+// the wrong files and report clean.
+function run_scan(binary: string, staged_files: ReadonlyArray<string>): number {
+	const result = execaSync(binary, build_scan_arguments(staged_files), {
+		stdio: 'inherit',
+		reject: false,
+	})
+
+	return resolve_spawn_exit(binary, result)
+}
+
+function main(staged_files: ReadonlyArray<string>, project_root: string): number {
+	const decision = plan_scan(staged_files, project_root)
+
+	if (decision.kind === 'scan') return run_scan(decision.binary, staged_files)
+
+	if (decision.notice !== undefined) console.warn(decision.notice)
+
+	return 0
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const exit_code = main(process.argv.slice(ARGV_OFFSET), process.cwd())
+
+	if (exit_code !== 0) process.exit(exit_code)
+}
+
+const secretlint_scan = {
+	build_scan_arguments,
+	main,
+	plan_scan,
+	resolve_secretlint_binary,
+	run_scan,
+}
+
+export { MISSING_NOTICE, secretlint_scan }

package/scripts/security/security-audit-logic.ts

@@ -0,0 +1,51 @@
+import path from 'node:path'
+
+const BINARY_NAME = 'osv-scanner'
+const LOCKFILE_PATH = 'pnpm-lock.yaml'
+
+// Where `josh audit:provision` puts a scanner it fetched itself, and the second place `josh audit`
+// looks once PATH has come up empty (joshuafolkken/kit#1563). Under `node_modules` because that is
+// the one directory every consumer of this package already ignores: a directory of our own would
+// need a `.gitignore` entry distributed to every repository `josh sync` reaches, and a home-relative
+// cache is refused outright by `no-global-shim-write.test.ts`. Losing the binary to `pnpm install`
+// costs one re-fetch at the next session start, which is the cheap side of that trade.
+const MANAGED_TOOL_SEGMENTS = ['node_modules', '.cache', 'josh-tools'] as const
+const WINDOWS_PLATFORM = 'win32'
+const WINDOWS_BINARY_SUFFIX = '.exe'
+
+const INSTALL_INSTRUCTIONS = [
+	'',
+	'Install options:',
+	'  Managed: pnpm josh audit:provision',
+	'  macOS:  brew install osv-scanner',
+	'  Go:     go install github.com/google/osv-scanner/v2/cmd/osv-scanner@latest',
+	'  Docker: docker run --rm -v "$PWD:/src" ghcr.io/google/osv-scanner --lockfile=/src/pnpm-lock.yaml',
+	'',
+	'Docs: https://google.github.io/osv-scanner/',
+].join('\n')
+
+function build_scanner_arguments(lockfile_path: string): ReadonlyArray<string> {
+	return [`--lockfile=${lockfile_path}`]
+}
+
+// The `.exe` suffix is not cosmetic on Windows: a file written without it is not executable there,
+// so the provisioner and the audit would disagree about whether the scanner had been installed.
+function build_managed_binary_path(project_root: string, platform: string): string {
+	const suffix = platform === WINDOWS_PLATFORM ? WINDOWS_BINARY_SUFFIX : ''
+
+	return path.join(project_root, ...MANAGED_TOOL_SEGMENTS, `${BINARY_NAME}${suffix}`)
+}
+
+function format_missing_binary_error(binary_name: string): string {
+	return `${binary_name} is not installed.\n${INSTALL_INSTRUCTIONS}`
+}
+
+const security_audit_logic = {
+	BINARY_NAME,
+	LOCKFILE_PATH,
+	build_managed_binary_path,
+	build_scanner_arguments,
+	format_missing_binary_error,
+}
+
+export { security_audit_logic }

package/scripts/security/security-audit-provision-logic.ts

@@ -0,0 +1,217 @@
+import { security_audit_logic } from './security-audit-logic'
+
+// Pinned, because an unpinned fetch is a binary nobody chose running against every lockfile in every
+// consumer repository. The checksums below belong to this exact tag: bumping one without the other
+// installs nothing at all, which is the failure that is visible rather than the one that is not.
+//
+// v2.6.0 is the floor because every earlier build parses only a fraction of pnpm-lock.yaml — the
+// 2.5.1 and 2.3.5 scanners both read 19 of 584 packages and reported the tree clean while four High
+// advisories sat in it (joshuafolkken/kit#2200). A scanner below the floor is a false negative, so
+// the provisioned version and the floor move together.
+const SCANNER_VERSION = '2.6.0'
+const MINIMUM_SCANNER_VERSION = SCANNER_VERSION
+const RELEASE_BASE_URL = 'https://github.com/google/osv-scanner/releases/download'
+
+const WINDOWS_PLATFORM = 'win32'
+const WINDOWS_ASSET_SUFFIX = '.exe'
+const STAGING_SUFFIX = '.download'
+
+// The asset is ~55 MB, and a link delivering it at 300 KB/s — measured, not hypothetical — takes
+// over three minutes. A `SessionStart` hook is waited on, so a single bound generous enough to
+// finish that download would be a three-minute stall at session start, and one short enough not to
+// stall would abort every slow link for ever.
+//
+// So the bound depends on how the command was reached. The automatic attempt gives up quickly and
+// says what to run; `--force` is a person typing a command in the foreground, where waiting for a
+// large download is exactly what was asked for. Declared here rather than beside the `fetch` so the
+// hook suite can derive the harness budget from the session bound: raising that without raising the
+// declared timeout would have the harness kill the request at a moment the script did not choose.
+const SESSION_DOWNLOAD_TIMEOUT_MS = 60_000
+const FORCED_DOWNLOAD_TIMEOUT_MS = 600_000
+
+function build_download_timeout(is_forced: boolean): number {
+	return is_forced ? FORCED_DOWNLOAD_TIMEOUT_MS : SESSION_DOWNLOAD_TIMEOUT_MS
+}
+
+// How long a failed attempt suppresses the next one. Without it an offline machine — or one behind a
+// proxy that blocks release assets — pays the whole download timeout again at every session start,
+// and the `SessionStart` matcher is empty, so that is every startup, resume, clear and compact rather
+// than once per machine. `--force` ignores the record, so a person who has just fixed their network
+// never has to wait it out.
+const MS_PER_HOUR = 3_600_000
+const HOURS_BEFORE_RETRY = 6
+const RETRY_INTERVAL_MS = HOURS_BEFORE_RETRY * MS_PER_HOUR
+
+// node's names for the host on the left, the release's names on the right. A host missing from
+// either map has no asset published for it, and the provisioner says so instead of guessing a URL.
+const PLATFORM_NAMES: Readonly<Record<string, string>> = {
+	darwin: 'darwin',
+	linux: 'linux',
+	win32: 'windows',
+}
+
+const ARCHITECTURE_NAMES: Readonly<Record<string, string>> = {
+	arm64: 'arm64',
+	x64: 'amd64',
+}
+
+// Transcribed from `osv-scanner_SHA256SUMS` of the tag above. Keyed by asset name so a wrong
+// platform mapping cannot silently pick up a neighboring platform's checksum — which is why the keys
+// are the release's own file names rather than anything this project's naming convention covers.
+/* eslint-disable @typescript-eslint/naming-convention -- upstream release asset file names */
+const ASSET_CHECKSUMS: Readonly<Record<string, string>> = {
+	'osv-scanner_darwin_amd64': '60c5296637e977b28eeda5c7f13573e447659a632922737f94d11fa7e30ad6ca',
+	'osv-scanner_darwin_arm64': '98c460dcd37de25819babd757d04542045b6243113e209edcd4d89fedb0256b4',
+	'osv-scanner_linux_amd64': 'ca69b3d3cd08f889a49dc0a383122f71cc528b83803671df5fd874d97485b108',
+	'osv-scanner_linux_arm64': '2c71403eb443d05891c4f268c3ad771cf4f16e5443463fd7851ef8f454d3c7e4',
+	'osv-scanner_windows_amd64.exe':
+		'e0ed7644118b717b028c249ee9d3515024e55e8510747ca08906eb96765354d6',
+	'osv-scanner_windows_arm64.exe':
+		'ca1379da0e408279ef2c85cde0846a903495738a91c7b065a208048437c1686c',
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+interface ScannerAsset {
+	name: string
+	url: string
+	sha256: string
+}
+
+function build_asset_name(platform: string, architecture: string): string | undefined {
+	const platform_name = PLATFORM_NAMES[platform]
+	const architecture_name = ARCHITECTURE_NAMES[architecture]
+	if (platform_name === undefined || architecture_name === undefined) return undefined
+
+	const suffix = platform === WINDOWS_PLATFORM ? WINDOWS_ASSET_SUFFIX : ''
+
+	return `${security_audit_logic.BINARY_NAME}_${platform_name}_${architecture_name}${suffix}`
+}
+
+function build_download_url(asset_name: string): string {
+	return `${RELEASE_BASE_URL}/v${SCANNER_VERSION}/${asset_name}`
+}
+
+// The staging file the download is written to before it is renamed onto the target. The process id
+// is what keeps two sessions of one project apart — the `SessionStart` matcher is empty, so a
+// `clear` during a startup's download is exactly that — and without it their writes interleave into
+// one file that both then rename into place, which the checksum cannot catch because each verified
+// its own buffer.
+function build_staging_path(target_path: string, process_id: number): string {
+	return `${target_path}.${String(process_id)}${STAGING_SUFFIX}`
+}
+
+// The whole "where do we fetch from" decision in one pure call, so the table above is testable
+// without a network round trip — which the unit suite forbids anyway (`test-network-guard.ts`).
+function resolve_asset(platform: string, architecture: string): ScannerAsset | undefined {
+	const name = build_asset_name(platform, architecture)
+	if (name === undefined) return undefined
+
+	const sha256 = ASSET_CHECKSUMS[name]
+	if (sha256 === undefined) return undefined
+
+	return { name, sha256, url: build_download_url(name) }
+}
+
+function format_already_present(location: string): string {
+	return `osv-scanner is already available (${location}); nothing to provision.`
+}
+
+function format_unsupported_platform(platform: string, architecture: string): string {
+	return `No pinned osv-scanner build for ${platform}/${architecture}; install it manually to run the pre-push audit.`
+}
+
+// The `--force` hint is on this message rather than only on the backoff one because the failure this
+// most often reports is the session bound running out on a slow link, and the command that finishes
+// that download is the one thing the reader needs.
+function format_download_failure(url: string, reason: string): string {
+	return `Could not fetch osv-scanner from ${url}: ${reason}. Run \`pnpm josh audit:provision --force\` to retry with a longer timeout; until then the pre-push audit will report the missing binary.`
+}
+
+// The mismatch is reported with both digests because the two things it can mean — a re-cut release
+// asset and a tampered download — are told apart by comparing the actual digest with the tag's own
+// published sums, and a message that hid it would leave nothing to compare.
+function format_checksum_mismatch(asset_name: string, expected: string, actual: string): string {
+	return `Checksum mismatch for ${asset_name}: expected ${expected}, got ${actual}. Nothing was installed.`
+}
+
+function format_installed(target_path: string): string {
+	return `Installed osv-scanner v${SCANNER_VERSION} at ${target_path}.`
+}
+
+function format_recent_failure(): string {
+	return `A previous attempt to provision osv-scanner failed less than ${String(HOURS_BEFORE_RETRY)} hours ago; not retrying at session start. Run \`pnpm josh audit:provision --force\` to try again now.`
+}
+
+// The catch-all, kept separate from `format_download_failure`: writing the binary can fail on its own
+// terms — a read-only mount, a full disk, a directory the running user may not create — and pointing
+// the reader at the network for a disk problem sends them to the wrong place entirely.
+function format_provision_error(reason: string): string {
+	return `Could not provision osv-scanner: ${reason}. The pre-push audit will report the missing binary.`
+}
+
+// `osv-scanner --version` prints `osv-scanner version: X.Y.Z` on its first line; the rest of the
+// block (`osv-scalibr version:`, `commit:`) is deliberately not matched so a scalibr version never
+// stands in for the scanner's. `undefined` means the output did not carry a scanner version at all,
+// which the caller treats as "cannot confirm the floor" rather than as a pass.
+const SCANNER_VERSION_PATTERN = /osv-scanner version:\s*(\d+\.\d+\.\d+)/u
+
+function parse_scanner_version(version_output: string): string | undefined {
+	return SCANNER_VERSION_PATTERN.exec(version_output)?.[1]
+}
+
+function to_version_parts(version: string): Array<number> {
+	return version.split('.').map(Number)
+}
+
+// Numeric per-segment compare rather than a string one, so `2.10.0` is not read as older than
+// `2.6.0`. A missing segment counts as zero, which is what lets a two-part version compare against a
+// three-part floor without a special case.
+function compare_versions(left: string, right: string): number {
+	const left_parts = to_version_parts(left)
+	const right_parts = to_version_parts(right)
+	const length = Math.max(left_parts.length, right_parts.length)
+
+	for (let index = 0; index < length; index += 1) {
+		const difference = (left_parts[index] ?? 0) - (right_parts[index] ?? 0)
+		if (difference !== 0) return difference
+	}
+
+	return 0
+}
+
+function meets_version_floor(version: string): boolean {
+	return compare_versions(version, MINIMUM_SCANNER_VERSION) >= 0
+}
+
+// Printed when the only scanner available parses the lockfile short of the floor: its "no issues
+// found" is not proof the tree is clean, only that a blinkered scanner read too little to object. The
+// distinction the acceptance criteria ask for — a small package count told apart from a genuine pass.
+function format_below_floor(version: string): string {
+	return `osv-scanner ${version} is below the required v${MINIMUM_SCANNER_VERSION}; older builds parse only part of pnpm-lock.yaml, so a clean result here is not proof the lockfile is clean. Run \`pnpm josh audit:provision --force\` to install v${SCANNER_VERSION}.`
+}
+
+const security_audit_provision_logic = {
+	FORCED_DOWNLOAD_TIMEOUT_MS,
+	RETRY_INTERVAL_MS,
+	SESSION_DOWNLOAD_TIMEOUT_MS,
+	SCANNER_VERSION,
+	MINIMUM_SCANNER_VERSION,
+	build_asset_name,
+	build_download_timeout,
+	build_download_url,
+	build_staging_path,
+	format_already_present,
+	format_below_floor,
+	format_checksum_mismatch,
+	format_download_failure,
+	format_installed,
+	format_provision_error,
+	format_recent_failure,
+	format_unsupported_platform,
+	meets_version_floor,
+	parse_scanner_version,
+	resolve_asset,
+}
+
+export { security_audit_provision_logic }
+export type { ScannerAsset }