@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/version/latest-if-required-cli.ts

@@ -0,0 +1,93 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { git_stash } from '#scripts/git/stash/git-stash'
+import { stash_pop_cli } from '#scripts/git/stash/stash-pop-cli'
+import { stash_push_cli } from '#scripts/git/stash/stash-push-cli'
+import { resolve_spawn_exit } from '#scripts/lib/spawn-exit'
+import { execaSync } from 'execa'
+import { latest_scope_cli } from './latest-scope-cli'
+
+// `josh latest:if-required` — the dependency update a run owes, in one call.
+//
+// `latest:scope` decides; on `required` the tree is set aside, `josh latest` runs, and the stash is
+// popped by its message. Four procedures used to spell that sequence out, and each copy was one more
+// place to drift from the others. `josh latest` itself stays a fixed `sh -c` chain that takes no
+// arguments, so the conditional form is its own command rather than a flag on it.
+//
+// **Every failure leaves the stash where it is.** A failed update can leave `package.json` half
+// rewritten, and a conflicted pop is a stash git keeps — popping onto either would bury the work
+// under conflicts, so the command stops with the message to pop it by.
+
+const ARGV_OFFSET = 2
+const USAGE = 'Usage: josh latest:if-required'
+const STASH_MESSAGE = 'josh latest'
+const LATEST_COMMAND: ReadonlyArray<string> = ['josh', 'latest']
+const PNPM = 'pnpm'
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const KEPT_STASH_HINT = `the stash is kept — pop it with \`pnpm josh stash:pop "${STASH_MESSAGE}"\``
+// A conflicted pop has already applied the stash, so popping it again would apply it twice.
+const CONFLICTED_STASH_HINT = `the stash "${STASH_MESSAGE}" is applied and still kept — resolve the conflicts, then drop it`
+
+function run_latest(): number {
+	const result = execaSync(PNPM, LATEST_COMMAND, { stdio: 'inherit', reject: false })
+
+	return resolve_spawn_exit(PNPM, result)
+}
+
+function stop(reason: string): number {
+	console.error(`latest:if-required stopped: ${reason}`)
+
+	return FAILURE_EXIT_CODE
+}
+
+function refuse(): number {
+	console.error(USAGE)
+
+	return FAILURE_EXIT_CODE
+}
+
+async function restore(): Promise<number> {
+	const code = await stash_pop_cli.run([STASH_MESSAGE])
+
+	if (code !== SUCCESS_EXIT_CODE) return stop(`the pop failed — ${KEPT_STASH_HINT}`)
+	if (await git_stash.has_conflict()) return stop(`the pop conflicted — ${CONFLICTED_STASH_HINT}`)
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function update(): Promise<number> {
+	const verdict = await stash_push_cli.set_aside({ message: STASH_MESSAGE, dir: undefined })
+	const is_stashed = verdict === stash_push_cli.STASHED_VERDICT
+	const code = run_latest()
+
+	if (code !== SUCCESS_EXIT_CODE) {
+		return stop(is_stashed ? `josh latest failed — ${KEPT_STASH_HINT}` : 'josh latest failed')
+	}
+
+	return is_stashed ? await restore() : SUCCESS_EXIT_CODE
+}
+
+// The scope on stdout and its reason on stderr, the split `latest:scope` prints in, so the log
+// says why the update ran or did not.
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	if (argv.length > 0) return refuse()
+
+	const decision = latest_scope_cli.scope_decision()
+
+	console.info(decision.scope)
+	console.error(decision.reason)
+	if (decision.scope === latest_scope_cli.SKIPPED_SCOPE) return SUCCESS_EXIT_CODE
+
+	return await update()
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const latest_if_required_cli = { run, STASH_MESSAGE }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { latest_if_required_cli }

package/scripts/version/latest-lane-guard-main.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { latest_lane_guard } from './latest-lane-guard'
+
+// The `josh latest:guard` entry, kept apart from `latest-lane-guard.ts` because `latest:scope` imports
+// that one: a bundle is one file, so a main guard there would fire for every command that carries it
+// (joshuafolkken/kit#4186). The guard takes no arguments and sets its own exit code.
+if (process.argv[1] === fileURLToPath(import.meta.url)) latest_lane_guard.main()

package/scripts/version/latest-lane-guard.ts

@@ -1,5 +1,3 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { lane_paths, type LaneEnvironment } from '#scripts/lane/lane-paths'
 
 // Refuse a dependency update inside a lane.
@@ -44,6 +42,4 @@ const latest_lane_guard = {
 	main,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) main()
-
 export { latest_lane_guard }

package/scripts/version/latest-scope-cli.ts

@@ -1,5 +1,3 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { latest_lane_guard } from './latest-lane-guard'
 import { latest_stamp, type LatestStamp } from './latest-stamp'
 
@@ -14,7 +12,6 @@ import { latest_stamp, type LatestStamp } from './latest-stamp'
 // paths*, and this decides from *when the last run happened*. The flag parsing and the printing are the small half;
 // the read of the diff is what that module exists for, and this command never makes one.
 
-const ARGV_OFFSET = 2
 const USAGE = 'Usage: josh latest:scope [--record] [--json]'
 const JSON_KEY = 'scope'
 const JSON_FLAG = '--json'
@@ -124,10 +121,6 @@ function run(argv: ReadonlyArray<string>): number {
 	return 0
 }
 
-function main(argv: ReadonlyArray<string>): void {
-	process.exitCode = run(argv)
-}
-
 const latest_scope_cli = {
 	decide,
 	JSON_KEY,
@@ -140,6 +133,4 @@ const latest_scope_cli = {
 	USAGE,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(ARGV_OFFSET))
-
 export { latest_scope_cli }

package/scripts/version/latest-scope-main.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { latest_scope_cli } from './latest-scope-cli'
+
+// The `josh latest:scope` entry, kept apart from `latest-scope-cli.ts` because other modules import
+// that one: a bundle is one file, so a main guard there would fire for every command that carries it
+// (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = latest_scope_cli.run(process.argv.slice(ARGV_OFFSET))
+}

package/scripts/version/latest-update.ts

@@ -6,6 +6,7 @@
  */
 import { readFileSync, writeFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
+import { PACKAGE_JSON } from '#scripts/lib/package-manifest'
 import { file_reader } from '#scripts/lib/read-file'
 import { lockfile_overrides } from '#scripts/overrides/lockfile-overrides'
 import { overrides_files } from '#scripts/overrides/overrides-files'
@@ -16,7 +17,6 @@ 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'
 const LOCKFILE_PATH = 'pnpm-lock.yaml'
 
 interface TreeSnapshot {
@@ -44,7 +44,7 @@ function run_update_stages(stages: Array<Array<string>>): number {
 
 function take_snapshot(): TreeSnapshot {
 	return {
-		package_json: readFileSync(PACKAGE_JSON_PATH, 'utf8'),
+		package_json: readFileSync(PACKAGE_JSON, 'utf8'),
 		lockfile: file_reader.read_file_or_empty(LOCKFILE_PATH),
 	}
 }
@@ -54,7 +54,7 @@ function take_snapshot(): TreeSnapshot {
 // "the latest release is <older>". The captured lockfile still carries the resolved URL and
 // integrity, which installs fine.
 function restore_snapshot(snapshot: TreeSnapshot): void {
-	writeFileSync(PACKAGE_JSON_PATH, snapshot.package_json)
+	writeFileSync(PACKAGE_JSON, snapshot.package_json)
 	if (snapshot.lockfile.length > 0) writeFileSync(LOCKFILE_PATH, snapshot.lockfile)
 }
 
@@ -71,7 +71,7 @@ function report_kept_back(regressions: ReadonlyArray<VersionRegression>): void {
 const PNPM_UPDATE_ALL_TIERS = ['pnpm', 'update']
 
 function build_update_commands(): Array<Array<string>> {
-	const content = readFileSync(PACKAGE_JSON_PATH, 'utf8')
+	const content = readFileSync(PACKAGE_JSON, 'utf8')
 	const latest = overrides_check.build_update_command(
 		overrides_files.read_current_overrides(),
 		content,
@@ -87,7 +87,7 @@ interface UpdateOutcome {
 }
 
 function find_regressions_after_update(snapshot: TreeSnapshot): Array<VersionRegression> {
-	const after = readFileSync(PACKAGE_JSON_PATH, 'utf8')
+	const after = readFileSync(PACKAGE_JSON, 'utf8')
 
 	return latest_regression.find_regressions(snapshot.package_json, after)
 }

package/scripts/version/npm-registry.ts

@@ -1,6 +1,5 @@
 import { json_value } from '#scripts/lib/json-value'
-import { FETCH_TIMEOUT_MS } from '#scripts/lib/timeouts'
-import { migrate_logic } from '#scripts/registry-migration/migrate-logic'
+import { COMMAND_TIMEOUT_MS, FETCH_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execaSync } from 'execa'
 import semver from 'semver'
 import { z } from 'zod'
@@ -18,8 +17,19 @@ const SCOPE_SEPARATOR = '/'
 const ENCODED_SCOPE_SEPARATOR = '%2f'
 const SCOPE_PATTERN = /^@[^/]+(?=\/)/u
 const SCOPE_REGISTRY_SUFFIX = ':registry'
+const GITHUB_REGISTRY_HOST = 'npm.pkg.github.com'
+const PNPM = 'pnpm'
+const JSON_FLAG = '--json'
+const FAILURE_EXIT_CODE = 1
 const github_scopes = new Map<string, boolean>()
 
+type ViewFormat = 'json' | 'text'
+
+interface ViewAnswer {
+	exit_code: number
+	stdout: string
+}
+
 // The version commands are synchronous end to end and exported that way to consumers, so the
 // request runs in a child Node process rather than turning the whole chain async. Node's own
 // `fetch` needs no external binary, and a non-2xx answer exits non-zero so it reads as "no answer".
@@ -53,19 +63,30 @@ function read_packument(package_name: string, accept: string): unknown {
 	return json_value.parse_or_undefined(result.stdout)
 }
 
-// Whether this checkout installs the package's scope from GitHub Packages, read with the same
-// `pnpm config get` `josh registry:migrate` uses (project `.npmrc` over user `~/.npmrc`). The two
+// The host is compared, not searched for, so a registry carrying it only in its path is not GitHub.
+function is_github_registry(value: string): boolean {
+	try {
+		const url = new URL(value)
+
+		return url.protocol === 'https:' && url.hostname === GITHUB_REGISTRY_HOST
+	} catch {
+		return false
+	}
+}
+
+// Whether this checkout installs the package's scope from GitHub Packages, read with
+// `pnpm config get` (project `.npmrc` over user `~/.npmrc`). The two
 // registries are published by parallel jobs and can drift, so a consumer routed to GitHub Packages
 // keeps reading it: public npm could otherwise offer a release its registry does not carry yet.
 // Memoized per scope — kit and app-kit share one, and one report asks for both packages.
 function is_github_scope(scope: string): boolean {
 	const is_cached_github = github_scopes.get(scope)
 	if (is_cached_github !== undefined) return is_cached_github
-	const result = execaSync('pnpm', ['config', 'get', `${scope}${SCOPE_REGISTRY_SUFFIX}`], {
+	const result = execaSync(PNPM, ['config', 'get', `${scope}${SCOPE_REGISTRY_SUFFIX}`], {
 		reject: false,
 		timeout: FETCH_TIMEOUT_MS,
 	})
-	const is_github = result.exitCode === 0 && migrate_logic.is_github_tarball(result.stdout.trim())
+	const is_github = result.exitCode === 0 && is_github_registry(result.stdout.trim())
 
 	github_scopes.set(scope, is_github)
 
@@ -106,6 +127,21 @@ function has_public_version(package_name: string, version: string): boolean {
 	return parsed.success && parsed.data.time[version] !== undefined
 }
 
+// A `pnpm view` answer, for a question that has to see what the package manager sees: the
+// checkout's own registry routing, and safe-chain's minimum-age filter when it is shimmed on PATH.
+// `pnpm` rather than `npm`, because npm refuses to run at all inside a project whose
+// `devEngines.packageManager` names pnpm with an `onFail` other than `"warn"` / `"ignore"` (kit
+// ships `"download"`), failing with EBADDEVENGINES instead of answering.
+function view(spec: string, field: string, format: ViewFormat = 'text'): ViewAnswer {
+	const format_arguments = format === 'json' ? [JSON_FLAG] : []
+	const result = execaSync(PNPM, ['view', spec, field, ...format_arguments], {
+		reject: false,
+		timeout: COMMAND_TIMEOUT_MS,
+	})
+
+	return { exit_code: result.exitCode ?? FAILURE_EXIT_CODE, stdout: result.stdout }
+}
+
 // The version itself, or nothing when it is not exactly a semver version.
 function valid_version(value: string): string | undefined {
 	return version_schema.safeParse(value).success ? value : undefined
@@ -117,6 +153,8 @@ const npm_registry = {
 	read_latest,
 	read_release_times,
 	valid_version,
+	view,
 }
 
 export { npm_registry }
+export type { ViewAnswer }

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

@@ -9,8 +9,8 @@ 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 { PACKAGE_JSON } from '#scripts/lib/package-manifest'
+import { npm_registry } from './npm-registry'
 import { peer_floor } from './peer-floor'
 import {
 	publishable_range,
@@ -19,7 +19,6 @@ import {
 	type RangeProbe,
 } from './publishable-range'
 
-const PACKAGE_JSON_PATH = 'package.json'
 const FAILURE_EXIT_CODE = 1
 const NODE_MODULES = 'node_modules'
 
@@ -27,18 +26,8 @@ const NODE_MODULES = 'node_modules'
 // managers on PATH, so the answer comes back already filtered by the same minimum-age policy a
 // consumer installs under. A plain fetch would read the unfiltered registry and pass a range no
 // consumer can resolve — the exact blind spot this guard exists to close.
-//
-// `pnpm view` rather than `npm view` because npm refuses to run at all inside a project whose
-// `devEngines.packageManager` names pnpm with an `onFail` other than `"warn"` / `"ignore"` (kit
-// ships `"download"`, which npm refuses on just the same), failing every probe with
-// EBADDEVENGINES instead of answering. Both are shimmed, so the filtered view is preserved.
 function probe_range(name: string, range: string): ProbeResult {
-	const result = execaSync('pnpm', ['view', `${name}@${range}`, 'version'], {
-		reject: false,
-		timeout: COMMAND_TIMEOUT_MS,
-	})
-
-	return { exit_code: result.exitCode ?? FAILURE_EXIT_CODE, stdout: result.stdout }
+	return npm_registry.view(`${name}@${range}`, 'version')
 }
 
 function report(violations: ReadonlyArray<PublishedRange>, total: number): number {
@@ -90,14 +79,14 @@ function check_peer_floors(
 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))
+		.map((package_name) => path.join(project_root, NODE_MODULES, package_name, PACKAGE_JSON))
 		.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 {
-	const package_json_content = readFileSync(PACKAGE_JSON_PATH, 'utf8')
+	const package_json_content = readFileSync(PACKAGE_JSON, '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)

package/scripts/version/release-age.ts

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs'
 import path from 'node:path'
+import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
 import { yaml_document } from '#scripts/lib/yaml-document'
 import semver from 'semver'
 import { z } from 'zod'
@@ -20,7 +21,6 @@ const workspace_age_schema = z.object({ minimumReleaseAge: z.number().int().nonn
 // A version → ISO publish date map, the shape both the registry and the GitHub Packages API are
 // reduced to before the aged-version selection runs.
 const release_times_schema = z.record(z.string(), z.string())
-const MS_PER_MINUTE = 60_000
 
 function parse_workspace(workspace_content: string): unknown {
 	try {

package/scripts/version/release-hold.ts

@@ -1,3 +1,4 @@
+import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
 import semver from 'semver'
 import { release_age } from './release-age'
 
@@ -18,7 +19,6 @@ import { release_age } from './release-age'
 // which is why this explanation is attached there and nowhere else.
 
 const MINUTES_PER_HOUR = 60
-const MS_PER_MINUTE = 60_000
 const HOLD_LABEL = 'Held:'
 
 // Whether `latest` is itself inside the window — the precondition for a hold existing at all. Without

package/scripts/version/release-window.ts

@@ -0,0 +1,38 @@
+import path from 'node:path'
+import { file_reader } from '#scripts/lib/read-file'
+import { yaml_document } from '#scripts/lib/yaml-document'
+import { z } from 'zod'
+import { release_age } from './release-age'
+
+// The release-age window a workspace declares — its minutes and the packages exempt from it. This is
+// the one reading every mirror of the window derives from: Safe Chain's `.aikido` and Dependabot's
+// `cooldown` both take it from here rather than parsing `pnpm-workspace.yaml` themselves.
+const WORKSPACE_FILE = 'pnpm-workspace.yaml'
+const exclusions_schema = z.object({ minimumReleaseAgeExclude: z.array(z.string()).optional() })
+
+// The window a project without a declared one is held to, in minutes (three days). kit's own
+// `pnpm-workspace.yaml` declares the same value.
+const DEFAULT_RELEASE_AGE_MINUTES = 4320
+
+interface ReleaseWindow {
+	minutes: number | undefined
+	exclusions: ReadonlyArray<string>
+}
+
+function parse_release_window(workspace: string): ReleaseWindow {
+	const exclusions = exclusions_schema.parse(yaml_document.parse_yaml(workspace))
+
+	return {
+		minutes: release_age.parse_declared_minimum_release_age(workspace),
+		exclusions: exclusions.minimumReleaseAgeExclude ?? [],
+	}
+}
+
+// An absent workspace file reads as an empty one: no declared window and no exclusions.
+function read_release_window(root: string): ReleaseWindow {
+	return parse_release_window(file_reader.read_file_or_empty(path.join(root, WORKSPACE_FILE)))
+}
+
+const release_window = { parse_release_window, read_release_window }
+
+export { DEFAULT_RELEASE_AGE_MINUTES, release_window, type ReleaseWindow }

package/scripts/version/running-binary.ts

@@ -1,9 +1,9 @@
 import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { json_value } from '#scripts/lib/json-value'
+import { PACKAGE_JSON } from '#scripts/lib/package-manifest'
 import { package_version_schema } from '#scripts/lib/schemas'
 
-const PACKAGE_JSON = 'package.json'
 // Scripts live two levels under the package root (scripts/<group>/<file>.ts), so the running
 // binary's own package.json is reached by walking up twice from the script directory.
 const SCRIPT_DEPTH_FROM_ROOT = ['..', '..'] as const

package/scripts/version/safe-chain-version-update.ts

@@ -1,20 +1,15 @@
-import { COMMAND_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { ci_installer_pin } from '#scripts/safe-chain/ci-installer-pin'
 import { npm_registry } from '#scripts/version/npm-registry'
-import { execaSync } from 'execa'
 
 const SAFE_CHAIN_PKG = '@aikidosec/safe-chain'
 
 // The registry's answer is trusted only as an exact semver version: it ends up in workflow files and
 // in the installer URL.
 function fetch_latest_version(): string | undefined {
-	const result = execaSync('npm', ['view', SAFE_CHAIN_PKG, 'version'], {
-		reject: false,
-		timeout: COMMAND_TIMEOUT_MS,
-	})
-	if (result.exitCode !== 0 || !result.stdout) return undefined
+	const answer = npm_registry.view(SAFE_CHAIN_PKG, 'version')
+	if (answer.exit_code !== 0 || !answer.stdout) return undefined
 
-	return npm_registry.valid_version(result.stdout.trim())
+	return npm_registry.valid_version(answer.stdout.trim())
 }
 
 // The hash-verified installer pinned in the workflows is the one place a safe-chain release is

package/scripts/version/version-targets.ts

@@ -1,11 +1,10 @@
 import path from 'node:path'
 import { json_value } from '#scripts/lib/json-value'
-import { file_reader } from '#scripts/lib/read-file'
+import { package_manifest } from '#scripts/lib/package-manifest'
 import { package_version_schema, pnpm_ls_global_schema } from '#scripts/lib/schemas'
 import { execaSync } from 'execa'
 
 const NODE_MODULES = 'node_modules'
-const PACKAGE_JSON = 'package.json'
 
 // Build the `pnpm ls -g --json <package>` arguments for the package being checked.
 function build_pnpm_ls_arguments(package_name: string): Array<string> {
@@ -21,40 +20,25 @@ function parse_global_version(stdout: string, package_name: string): string | un
 	return parsed.data[0]?.dependencies?.[package_name]?.version
 }
 
-// Read the project-local version from a node_modules package.json string. Undefined when the
-// file is missing (raw is undefined) or malformed.
-function parse_project_version(raw: string | undefined): string | undefined {
-	if (raw === undefined) return undefined
-	const parsed = package_version_schema.safeParse(json_value.parse_or_undefined(raw))
-
-	return parsed.success ? parsed.data.version : undefined
-}
-
 function read_global_version(package_name: string): string | undefined {
 	const result = execaSync('pnpm', build_pnpm_ls_arguments(package_name), { reject: false })
 
 	return parse_global_version(result.stdout, package_name)
 }
 
-function project_package_path(cwd: string, package_name: string): string {
-	return path.join(cwd, NODE_MODULES, package_name, PACKAGE_JSON)
-}
-
+// Read the project-local version from <cwd>/node_modules/<package>/package.json. Undefined when the
+// file is missing or malformed.
 function read_project_version(cwd: string, package_name: string): string | undefined {
-	const package_path = project_package_path(cwd, package_name)
-	const raw = file_reader.read_optional(package_path)
+	const package_directory = path.join(cwd, NODE_MODULES, package_name)
 
-	return parse_project_version(raw)
+	return package_manifest.read_manifest_if_valid(package_directory, package_version_schema)?.version
 }
 
 // Read the current project's own declared version from <cwd>/package.json. This is the version
 // that `josh bump` increments — distinct from read_project_version, which reads the installed kit
 // package version under node_modules.
 function read_workspace_version(cwd: string): string | undefined {
-	const package_path = path.join(cwd, PACKAGE_JSON)
-	const raw = file_reader.read_optional(package_path)
-
-	return parse_project_version(raw)
+	return package_manifest.read_manifest_if_valid(cwd, package_version_schema)?.version
 }
 
 // `format_project_version_line` / `project_version_line` lived here and formatted
@@ -67,15 +51,9 @@ function read_workspace_version(cwd: string): string | undefined {
 const version_targets = {
 	build_pnpm_ls_arguments,
 	parse_global_version,
-	parse_project_version,
 	read_global_version,
 	read_project_version,
-	project_package_path,
 	read_workspace_version,
-	// The manifest's filename. Exported rather than re-declared in each of `josh release`'s two
-	// halves: the module that already owns "where the project's manifest is"
-	// is where the name belongs.
-	PACKAGE_JSON,
 }
 
 export { version_targets }

package/templates/dependabot.yml

@@ -0,0 +1,29 @@
+version: 2
+updates:
+  # The local composite actions pin actions of their own, and Dependabot reads only the directories
+  # it is given — `/` covers `.github/workflows` and no `.github/actions/*/action.yml`.
+  - package-ecosystem: 'github-actions'
+    directories:
+      - '/'
+      - '/.github/actions/*'
+    schedule:
+      interval: 'weekly'
+    cooldown:
+      default-days: 3
+  # Version updates are disabled: `josh latest` runs at the start of every fullrun / halfrun /
+  # queue and already bumps npm dependencies to latest, so Dependabot's weekly PRs only duplicate
+  # it and were being closed unmerged after consuming a full CI run. `open-pull-requests-limit: 0`
+  # disables version updates only — security update PRs "are not subject to this limit and do not
+  # count toward it" (GitHub's Dependabot options reference), so an advisory still opens a PR,
+  # which is the one case `josh latest` does not cover on its own. That fallback needs Dependabot
+  # security updates enabled on the repository (Settings > Advanced Security); without it this file
+  # leaves no npm Dependabot PRs at all. See joshuafolkken/kit#803.
+  - package-ecosystem: 'npm'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+    open-pull-requests-limit: 0
+    cooldown:
+      default-days: 3
+      exclude:
+        - 'vite'

package/templates/gitignore

@@ -78,7 +78,10 @@ e2e/.auth/chrome-profile/
 .claude/scheduled_tasks.lock
 .claude/tmp/
 
-# Run handoff notes (written for josh run:cut --handoff); they belong in .claude/tmp/, and the
+# Scratch files any agent writes (Issue / PR bodies, plans, handoffs, logs); the rest of .josh/ is tracked
+.josh/tmp/
+
+# Run handoff notes (written for josh run:cut --handoff); they belong in .josh/tmp/, and the
 # names below are the ones that were once written beside the code and committed with it
 /.git-handoff-*.json
 /.josh-handoff-*.json

package/templates/pnpm-workspace.basic.yaml

@@ -6,5 +6,5 @@ allowBuilds:
   unrs-resolver: true
 
 # pnpm 12 reads these settings from this file only; the same lines in .npmrc are ignored (kit #3267).
-minimumReleaseAge: 1440
+minimumReleaseAge: 4320
 engineStrict: true

package/templates/sonar-project.properties

@@ -71,8 +71,9 @@ sonar.issue.ignore.multicriteria.e14.resourceKey=**/*
 
 # Files to exclude from the duplicate check.
 # Snapshot files (.snap) contain machine-generated repetitive patterns and are not authored code.
-# Command-registry files (josh-commands-*.ts) are data definitions that follow a fixed schema;
-# structural similarity between entries is inherent and expected, not logic duplication.
+# Command-registry files (josh-commands-*.ts) are data
+# definitions that follow a fixed schema; structural similarity between entries is inherent and
+# expected, not logic duplication.
 sonar.cpd.exclusions=**/*.test.ts,**/*.spec.ts,**/*.e2e.ts,**/*.snap,**/josh-commands-*.ts
 
 # Use SonarCloud-compatible tsconfig

package/templates/workflows/ci.yml

@@ -125,6 +125,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup Node.js
+        id: setup-node
         uses: ./.github/actions/setup-node
 
       - name: Configure GitHub Packages authentication for existing projects
@@ -144,11 +145,18 @@ jobs:
           # save nothing back under the key it already hit — a cold lint on every later run.
           # joshuafolkken/kit#2054: the commit sha makes each run save its warmed cache under a fresh
           # key, while the sha-less prefix restores the newest entry from an earlier run.
-          key: ${{ runner.os }}-eslint-cache-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('eslint.config.js', 'eslint/**/*.js') }}-${{ github.sha }}
+          # joshuafolkken/kit#4346: ESLint hashes `process.version` into every entry, and runner
+          # images carry different Node.js patch releases for `'24'`, so a restore across two of them
+          # lints cold. The resolved version leads every key: each release keeps its own lineage.
+          # joshuafolkken/kit#4496: the key is not built from kit's toolchain input list — the cache
+          # is restored before the install, and this workflow has no kit source to run. The lockfile
+          # and eslint config hashes move it with the two inputs ESLint's own per-entry check does
+          # not cover.
+          key: ${{ runner.os }}-eslint-cache-${{ steps.setup-node.outputs.node-version }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('eslint.config.js', 'eslint/**/*.js') }}-${{ github.sha }}
           restore-keys: |
-            ${{ runner.os }}-eslint-cache-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('eslint.config.js', 'eslint/**/*.js') }}-
-            ${{ runner.os }}-eslint-cache-${{ hashFiles('pnpm-lock.yaml') }}-
-            ${{ runner.os }}-eslint-cache-
+            ${{ runner.os }}-eslint-cache-${{ steps.setup-node.outputs.node-version }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('eslint.config.js', 'eslint/**/*.js') }}-
+            ${{ runner.os }}-eslint-cache-${{ steps.setup-node.outputs.node-version }}-${{ hashFiles('pnpm-lock.yaml') }}-
+            ${{ runner.os }}-eslint-cache-${{ steps.setup-node.outputs.node-version }}-
 
       - name: Setup cspell cache
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0

package/templates/workflows/github-release.yml

@@ -41,6 +41,10 @@ jobs:
         env:
           DISPATCH_TAG: ${{ github.event.client_payload.tag }}
         run: |
+          if ! [[ "$DISPATCH_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+([.-][0-9A-Za-z.-]+)?$ ]]; then
+            echo "::error::Invalid tag format: $DISPATCH_TAG" >&2
+            exit 1
+          fi
           echo "tag=$DISPATCH_TAG" >> "$GITHUB_OUTPUT"
           if [ -f .github/workflows/publish.yml ]; then
             echo "workflow=publish.yml" >> "$GITHUB_OUTPUT"