@joshuafolkken/kit 1.872.0

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

@@ -0,0 +1,186 @@
+#!/usr/bin/env tsx
+import { chmodSync, mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { security_audit } from './security-audit'
+import { security_audit_logic } from './security-audit-logic'
+import { security_audit_provision_logic, type ScannerAsset } from './security-audit-provision-logic'
+
+const EXECUTABLE_MODE = 0o755
+const FAILURE_STAMP_PREFIX = 'josh-audit-provision-'
+const FORCE_FLAG = '--force'
+const PATH_LOCATION = 'on PATH'
+const { RETRY_INTERVAL_MS } = security_audit_provision_logic
+
+function describe_error(error: unknown): string {
+	return error instanceof Error ? error.message : String(error)
+}
+
+// `content` absent is the failure, and `reason` says which one. A 404 — what a bumped version whose
+// asset was renamed looks like, and the one failure that never fixes itself — would otherwise read
+// exactly like a transient 503, and a rejected request like neither.
+interface DownloadOutcome {
+	content?: Buffer
+	reason: string
+}
+
+interface ProvisionOutcome {
+	message: string
+	is_installed: boolean
+}
+
+// The rejection is caught here rather than left to `attempt`: being offline, behind a proxy that
+// refuses the host, or past the timeout is a *fetch* failure, and reporting it through the generic
+// catch-all would drop the release URL out of the message that names where the fetch went.
+async function download(url: string, timeout_ms: number): Promise<DownloadOutcome> {
+	try {
+		const response = await fetch(url, { signal: AbortSignal.timeout(timeout_ms) })
+		if (!response.ok) return { reason: `HTTP ${String(response.status)}` }
+
+		return { content: Buffer.from(await response.arrayBuffer()), reason: '' }
+	} catch (error) {
+		return { reason: describe_error(error) }
+	}
+}
+
+// Staged beside the target and renamed onto it, under a name carrying this process's id. A download
+// interrupted halfway would otherwise leave a truncated file at the path `josh audit` spawns; and a
+// shared staging name would let two sessions of the same project — the `SessionStart` matcher is
+// empty, so a `clear` during a startup's download is exactly that — interleave their writes into one
+// file that both then rename into place, which the checksum cannot catch because it was verified
+// against each process's own buffer. The `finally` removes the staging file on every failing path.
+function install(target_path: string, content: Buffer): void {
+	const staging_path = security_audit_provision_logic.build_staging_path(target_path, process.pid)
+
+	mkdirSync(path.dirname(target_path), { recursive: true })
+
+	try {
+		writeFileSync(staging_path, content)
+		chmodSync(staging_path, EXECUTABLE_MODE)
+		renameSync(staging_path, target_path)
+	} finally {
+		rmSync(staging_path, { force: true })
+	}
+}
+
+function failure_stamp_path(target_path: string): string {
+	return stamp_file.stamp_path(FAILURE_STAMP_PREFIX, target_path)
+}
+
+function is_in_backoff(target_path: string): boolean {
+	const recorded = Number(stamp_file.read_stamp_text(failure_stamp_path(target_path)))
+
+	return Number.isFinite(recorded) && Date.now() - recorded < RETRY_INTERVAL_MS
+}
+
+function record_failure(target_path: string, message: string): string {
+	stamp_file.write_stamp(failure_stamp_path(target_path), Date.now())
+
+	return message
+}
+
+async function provision(
+	target_path: string,
+	asset: ScannerAsset,
+	timeout_ms: number,
+): Promise<ProvisionOutcome> {
+	const { format_checksum_mismatch, format_download_failure, format_installed } =
+		security_audit_provision_logic
+	const outcome = await download(asset.url, timeout_ms)
+
+	if (outcome.content === undefined) {
+		return { is_installed: false, message: format_download_failure(asset.url, outcome.reason) }
+	}
+
+	const actual = stamp_file.digest(outcome.content)
+
+	if (actual !== asset.sha256) {
+		return {
+			is_installed: false,
+			message: format_checksum_mismatch(asset.name, asset.sha256, actual),
+		}
+	}
+
+	install(target_path, outcome.content)
+
+	return { is_installed: true, message: format_installed(target_path) }
+}
+
+// The one place a failure is recorded, so the backoff covers a rejected fetch, a bad checksum and a
+// write that could not land alike — every reason the next session start would otherwise repeat.
+async function attempt(
+	target_path: string,
+	asset: ScannerAsset,
+	timeout_ms: number,
+): Promise<string> {
+	try {
+		const outcome = await provision(target_path, asset, timeout_ms)
+		if (!outcome.is_installed) return record_failure(target_path, outcome.message)
+
+		// Cleared on success, or a `pnpm install` that wipes the cache directory — which this design
+		// treats as costing one re-fetch — would instead be answered by a stale record telling the
+		// reader to pass `--force` for as long as the backoff runs.
+		stamp_file.remove_stamp(failure_stamp_path(target_path))
+
+		return outcome.message
+	} catch (error) {
+		return record_failure(
+			target_path,
+			security_audit_provision_logic.format_provision_error(describe_error(error)),
+		)
+	}
+}
+
+// PATH first, but only when its scanner meets the floor: a below-floor PATH build (or a leftover
+// managed copy from an earlier pinned version) reads a fraction of the lockfile and calls it clean
+// (joshuafolkken/kit#2200), so it must not be reported as "already available" — doing so is what
+// suppresses the fetch of a floor-meeting build. `is_executable_file` still guards the managed path
+// so a zero-byte or non-executable leftover is never spawned just to read its version.
+function existing_scanner(target_path: string): string | undefined {
+	const { BINARY_NAME } = security_audit_logic
+	if (security_audit.meets_floor(BINARY_NAME)) return PATH_LOCATION
+
+	const is_managed_usable =
+		security_audit.is_executable_file(target_path) && security_audit.meets_floor(target_path)
+
+	return is_managed_usable ? target_path : undefined
+}
+
+async function report(
+	project_root: string,
+	platform: string,
+	architecture: string,
+	is_forced: boolean,
+): Promise<string> {
+	const logic = security_audit_provision_logic
+	const target_path = security_audit_logic.build_managed_binary_path(project_root, platform)
+	const existing = existing_scanner(target_path)
+	if (existing !== undefined) return logic.format_already_present(existing)
+
+	const asset = logic.resolve_asset(platform, architecture)
+	if (asset === undefined) return logic.format_unsupported_platform(platform, architecture)
+	if (!is_forced && is_in_backoff(target_path)) return logic.format_recent_failure()
+
+	return await attempt(target_path, asset, logic.build_download_timeout(is_forced))
+}
+
+// Every failure is a printed line and a zero exit, deliberately: this runs at session start, and a
+// non-zero exit there would take an agent's whole session away over a tool it does not need yet.
+// The audit's own gate is unchanged — a scanner that never arrived still fails the pre-push run.
+async function main(): Promise<void> {
+	const is_forced = process.argv.includes(FORCE_FLAG)
+
+	try {
+		console.info(await report(PROJECT_ROOT, process.platform, process.arch, is_forced))
+	} catch (error) {
+		console.warn(security_audit_provision_logic.format_provision_error(describe_error(error)))
+	}
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+
+const security_audit_provision = { attempt, download, install, main, provision, report }
+
+export { security_audit_provision }

package/scripts/security/security-audit.ts

@@ -0,0 +1,132 @@
+#!/usr/bin/env tsx
+import { accessSync, constants, statSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { execaSync } from 'execa'
+import { security_audit_logic } from './security-audit-logic'
+import { security_audit_provision_logic } from './security-audit-provision-logic'
+
+const FAILURE_EXIT_CODE = 1
+const UNKNOWN_VERSION = 'unknown'
+
+// execa reports `exitCode: undefined` only when the binary could not be spawned
+// (ENOENT); a non-zero `--version` exit still means the binary exists.
+function is_binary_available(binary_name: string): boolean {
+	const result = execaSync(binary_name, ['--version'], { stdio: 'ignore', reject: false })
+
+	return result.exitCode !== undefined
+}
+
+// The scanner's own reported version, or `undefined` when it could not be spawned or printed nothing
+// a version could be read from. Captured through the default piped stdio rather than the `ignore` the
+// availability probe uses, because the version is exactly what has to be read back here.
+function scanner_version(binary_or_path: string): string | undefined {
+	const result = execaSync(binary_or_path, ['--version'], { reject: false })
+	if (result.exitCode === undefined) return undefined
+
+	return security_audit_provision_logic.parse_scanner_version(result.stdout)
+}
+
+// Whether the binary at this name or path parses the whole lockfile, i.e. is at or above the pinned
+// floor. A version that cannot be read is not the floor met — an unspawnable or version-less binary
+// is treated as below it, never as a pass (joshuafolkken/kit#2200).
+function meets_floor(binary_or_path: string): boolean {
+	const version = scanner_version(binary_or_path)
+
+	return version !== undefined && security_audit_provision_logic.meets_version_floor(version)
+}
+
+// Existence is not the question a provisioned binary has to answer. An interrupted install, a
+// `chmod` refused by a `noexec` mount or a zero-byte leftover all satisfy `existsSync`, and spawning
+// one of those fails with EACCES or ENOEXEC — an error that names neither the scanner nor how to get
+// one, and that `josh audit:provision` would refuse to repair because something is already there.
+function is_executable_file(candidate_path: string): boolean {
+	try {
+		accessSync(candidate_path, constants.X_OK)
+		const stats = statSync(candidate_path)
+
+		// `X_OK` succeeds on any traversable directory, and a directory's reported size is never zero,
+		// so both other clauses pass for one — reintroducing the very failure this check removes.
+		return stats.isFile() && stats.size > 0
+	} catch {
+		return false
+	}
+}
+
+interface ScannerChoice {
+	path: string
+	is_below_floor: boolean
+}
+
+// A provisioned copy counts only when it is both a real executable and at or above the floor: a
+// leftover from an earlier pinned version would otherwise be preferred over the PATH binary while
+// reading less of the lockfile than it should.
+function managed_scanner(project_root: string, platform: string): string | undefined {
+	const managed_path = security_audit_logic.build_managed_binary_path(project_root, platform)
+
+	return is_executable_file(managed_path) && meets_floor(managed_path) ? managed_path : undefined
+}
+
+// PATH first, but only when its scanner meets the floor: an older PATH build reads a fraction of the
+// lockfile and calls it clean (joshuafolkken/kit#2200), so a provisioned v2.6.0 is preferred over it
+// rather than the other way round (the preference of joshuafolkken/kit#1563 held only while every
+// build read the whole file). A below-floor PATH binary is the last resort, returned flagged so the
+// audit can warn that its clean result proves nothing. `undefined` means no scanner at all.
+function resolve_scanner(project_root: string, platform: string): ScannerChoice | undefined {
+	const { BINARY_NAME } = security_audit_logic
+	const has_path_binary = is_binary_available(BINARY_NAME)
+
+	if (has_path_binary && meets_floor(BINARY_NAME)) {
+		return { path: BINARY_NAME, is_below_floor: false }
+	}
+
+	const managed = managed_scanner(project_root, platform)
+	if (managed !== undefined) return { path: managed, is_below_floor: false }
+
+	return has_path_binary ? { path: BINARY_NAME, is_below_floor: true } : undefined
+}
+
+function run_scanner(scanner_path: string): number {
+	const { LOCKFILE_PATH, build_scanner_arguments } = security_audit_logic
+	const result = execaSync(scanner_path, [...build_scanner_arguments(LOCKFILE_PATH)], {
+		stdio: 'inherit',
+		reject: false,
+	})
+
+	return result.exitCode ?? FAILURE_EXIT_CODE
+}
+
+// The clean result of a below-floor scanner is warned about rather than trusted: it means only that
+// a blinkered build read too little of the lockfile to object, which the exit code cannot express.
+function warn_below_floor(scanner_path: string): void {
+	const version = scanner_version(scanner_path) ?? UNKNOWN_VERSION
+
+	console.warn(security_audit_provision_logic.format_below_floor(version))
+}
+
+function main(): never {
+	const { BINARY_NAME, format_missing_binary_error } = security_audit_logic
+	const choice = resolve_scanner(PROJECT_ROOT, process.platform)
+
+	if (choice === undefined) {
+		console.error(format_missing_binary_error(BINARY_NAME))
+		process.exit(FAILURE_EXIT_CODE)
+	}
+
+	if (choice.is_below_floor) warn_below_floor(choice.path)
+
+	process.exit(run_scanner(choice.path))
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main()
+
+const security_audit = {
+	is_binary_available,
+	is_executable_file,
+	meets_floor,
+	resolve_scanner,
+	run_scanner,
+	scanner_version,
+}
+
+export { security_audit }

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

@@ -0,0 +1,131 @@
+import { repo_setting, type RepoSettingStatus } from '#scripts/repo/repo-setting'
+
+// GitHub's Dependabot security-updates setting, as reported by
+// `GET /repos/{owner}/{repo}/automated-security-fixes`.
+//
+// joshuafolkken/kit#803 set `open-pull-requests-limit: 0` on the npm entry of the distributed
+// `.github/dependabot.yml`, which makes the security-advisory path the only remaining source of npm
+// Dependabot PRs. That path depends on this repository-level setting, which is opt-in and off by
+// default for private repositories — so a consumer that syncs the file without it gets zero npm
+// Dependabot PRs, advisories included. The failure is silent: no PR looks exactly like no advisory
+// (joshuafolkken/kit#805).
+//
+// `paused` is this setting's own third state, which is why the shared two-state classifier is only
+// half the answer here (see classify_security_updates).
+type SecurityUpdatesStatus = RepoSettingStatus | 'paused'
+
+const SETTING_LABEL = 'Dependabot security updates'
+const ENABLED_FIELD = 'enabled'
+const PAUSED_FIELD = 'paused'
+const ORIGIN_ISSUE = 'joshuafolkken/kit#803'
+
+// The remediation for `disabled`, addressed at the repository the report actually resolved.
+function enable_command(repo: string | undefined): string {
+	return `gh api -X PUT repos/${repo_setting.command_target(repo)}/automated-security-fixes`
+}
+
+// `paused` is held to the same standard as `enabled`: a present but non-boolean value means the
+// payload is not the one this code was written against, and guessing `enabled` from it would print
+// the false all-clear the module exists to prevent. Absent is the older response shape, not a pause.
+function classify_active(paused: unknown): SecurityUpdatesStatus {
+	if (paused === undefined) return 'enabled'
+	if (typeof paused !== 'boolean') return 'unreadable'
+
+	return paused ? 'paused' : 'enabled'
+}
+
+// Classify one `gh api` result. The shared classifier answers `enabled` / `disabled` / `unreadable`
+// off the `enabled` field — a failed call, unparseable output and a non-boolean field all landing on
+// `unreadable` — and only an affirmative answer is refined further by `paused`.
+function classify_security_updates(exit_code: number, stdout: string): SecurityUpdatesStatus {
+	const payload = repo_setting.parse_payload(exit_code, stdout)
+	const status = repo_setting.classify_boolean_setting(payload, ENABLED_FIELD)
+	if (status !== 'enabled') return status
+
+	return classify_active(repo_setting.read_field(payload, PAUSED_FIELD))
+}
+
+// Whether the status leaves npm security advisories unable to open a PR. `unreadable` is excluded:
+// it is worth reporting but it is not evidence of exposure.
+function is_exposed(status: SecurityUpdatesStatus): boolean {
+	return status === 'disabled' || status === 'paused'
+}
+
+// `disabled` and `paused` need different advice. The enable endpoint is a no-op on a paused
+// repository — it is already `enabled: true` — so printing it there would send the reader in a
+// circle and the same warning would return on the next sync.
+function format_exposed_detail(
+	status: SecurityUpdatesStatus,
+	repo: string | undefined,
+): ReadonlyArray<string> {
+	const remediation =
+		status === 'paused'
+			? [
+					'    enabled but paused, so no advisory pull request is opened.',
+					"    Resume it from the repository's Security → Dependabot page; re-running the enable",
+					'    API does not clear a pause.',
+				]
+			: [
+					'    off, so npm advisories open no pull request at all.',
+					`    Enable: ${enable_command(repo)}`,
+				]
+
+	return [
+		...remediation,
+		`    ${ORIGIN_ISSUE} disabled npm version updates, so this is the only remaining npm path.`,
+	]
+}
+
+// Why the setting could not be read. The two branches have different causes and must not share
+// wording: when the repository itself was never identified, admin access and Dependabot's state are
+// both beside the point, and pointing at a Security page names no page the reader can open.
+//
+// For an identified repository the causes are listed rather than asserted. GitHub answers 404 both
+// for a token without admin access and for a repository where Dependabot is not enabled, and the
+// same branch catches a timeout, an offline run and an unparseable body — so naming any one of them
+// as the cause would be a false diagnosis. No enable command here either: it would be wrong whenever
+// the setting is actually on and merely unreadable.
+function format_unreadable_detail(repo: string | undefined): ReadonlyArray<string> {
+	if (repo === undefined) {
+		return [
+			'    The repository could not be identified — `gh` is missing, unauthenticated, or this is',
+			'    not a GitHub remote.',
+		]
+	}
+
+	return [
+		'    No admin access, Dependabot not enabled for the repository, or the request failed',
+		'    (offline, timed out, or an unexpected response).',
+		"    Check the repository's Security → Dependabot page.",
+	]
+}
+
+// The report block for one repository: a single status line, plus the cause and its remediation when
+// the repository is exposed, or the two possible causes when the setting could not be read.
+function format_security_updates_report(
+	status: SecurityUpdatesStatus,
+	repo: string | undefined,
+): ReadonlyArray<string> {
+	const target = repo_setting.report_target(repo)
+	if (status === 'enabled') return [`  ✔ ${SETTING_LABEL}: enabled (${target})`]
+
+	if (!is_exposed(status)) {
+		return [
+			`  ⚠ ${SETTING_LABEL}: could not be read (${target}) — not checked, not necessarily off`,
+			...format_unreadable_detail(repo),
+		]
+	}
+
+	return [`  ⚠ ${SETTING_LABEL}: ${status} (${target})`, ...format_exposed_detail(status, repo)]
+}
+
+const security_updates_logic = {
+	SETTING_LABEL,
+	enable_command,
+	classify_security_updates,
+	is_exposed,
+	format_security_updates_report,
+}
+
+export type { SecurityUpdatesStatus }
+export { security_updates_logic }

package/scripts/security/security-updates.ts

@@ -0,0 +1,38 @@
+import { repo_setting } from '#scripts/repo/repo-setting'
+import { security_updates_logic, type SecurityUpdatesStatus } from './security-updates-logic'
+
+const SECURITY_FIXES_PATH = 'automated-security-fixes'
+
+// Read the repository's Dependabot security-updates setting. Never throws and never propagates a
+// non-zero exit: an unreadable answer is a reported status, not a command failure
+// (joshuafolkken/kit#805).
+function read_security_updates(repo: string): SecurityUpdatesStatus {
+	const { exit_code, stdout } = repo_setting.query_repo_api(`repos/${repo}/${SECURITY_FIXES_PATH}`)
+
+	return security_updates_logic.classify_security_updates(exit_code, stdout)
+}
+
+// Report the repository's setting as a blank-line-separated block. A repository that cannot be
+// resolved (no `gh`, not a GitHub remote) reports `unreadable` rather than skipping the check
+// silently — the whole point of joshuafolkken/kit#805 is that an absent answer must not look like a
+// clean one.
+//
+// `repo` is always supplied by the caller — deliberately not a default parameter. A default fires
+// on an explicitly-passed `undefined`, so `josh sync` handing over a failed lookup would silently
+// spawn `gh repo view` a second time, defeating the hoist in exactly the path where `gh` is already
+// known to be failing. `josh init` and `josh sync` already resolve the name for the Sonar config.
+function report_security_updates_section(repo: string | undefined): SecurityUpdatesStatus {
+	const status = repo === undefined ? 'unreadable' : read_security_updates(repo)
+
+	repo_setting.print_section(security_updates_logic.format_security_updates_report(status, repo))
+
+	return status
+}
+
+const security_updates = {
+	GH_TIMEOUT_MS: repo_setting.GH_TIMEOUT_MS,
+	read_security_updates,
+	report_security_updates_section,
+}
+
+export { security_updates }

package/scripts/security/sonar-file.ts

@@ -0,0 +1,44 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { init_logic } from '#scripts/init/init-logic'
+import type { SonarIdentifiers } from '#scripts/init/init-logic-sonar'
+
+function write_sonar_file(
+	template_source: string,
+	destination_path: string,
+	identifiers: SonarIdentifiers,
+): void {
+	const content = init_logic.apply_sonar_template(
+		readFileSync(template_source, 'utf8'),
+		identifiers.project_key,
+		identifiers.organization,
+	)
+
+	mkdirSync(path.dirname(destination_path), { recursive: true })
+	writeFileSync(destination_path, content)
+}
+
+function merge_sonar_file(
+	template_source: string,
+	destination_path: string,
+	identifiers: SonarIdentifiers,
+): void {
+	if (!existsSync(destination_path)) {
+		write_sonar_file(template_source, destination_path, identifiers)
+
+		return
+	}
+
+	const template_content = init_logic.apply_sonar_template(
+		readFileSync(template_source, 'utf8'),
+		identifiers.project_key,
+		identifiers.organization,
+	)
+	const existing = readFileSync(destination_path, 'utf8')
+
+	writeFileSync(destination_path, init_logic.merge_sonar_properties(existing, template_content))
+}
+
+const sonar_file = { write_sonar_file, merge_sonar_file }
+
+export { sonar_file }

package/scripts/self-sync-guard/index.ts

@@ -0,0 +1,5 @@
+// The public surface a downstream distribution package imports to refuse a sync aimed at its own
+// repository. Exported rather than left internal because app-kit and game-kit run the same kind of
+// copy and would otherwise each re-implement the detection (joshuafolkken/kit#868), which is the
+// duplication `managed-marker` was extracted to avoid for the workflow stamp.
+export { self_sync_guard } from './self-sync-guard-logic'

package/scripts/self-sync-guard/self-sync-guard-logic.ts

@@ -0,0 +1,98 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+
+// `josh sync` / `josh-app sync` / `josh-game sync` all copy a distribution package's files into a
+// consumer project. Run inside the package's OWN repository the direction reverses: the source of
+// truth is overwritten by the derived template, and the copy transforms fire against a project
+// where they are wrong (a `prompts/…` reference rewritten to `node_modules/@joshuafolkken/kit/…`
+// resolves nowhere, a workflow written from `templates/` loses the pins `.github/workflows` owns).
+// joshuafolkken/game-kit#447 is the incident; joshuafolkken/kit#868 reproduced the same damage in
+// kit — 14 files, including CLAUDE.md, tsconfig.json and both mapped workflows.
+//
+// The check lives here rather than in each package's sync so the three distributors share one
+// implementation: a second copy would drift, and a distributor that spelled the signal differently
+// would keep exactly the hole this closes.
+const MANIFEST_NAME = 'package.json'
+
+function read_package_name(directory: string): string | undefined {
+	try {
+		const manifest: unknown = JSON.parse(readFileSync(path.join(directory, MANIFEST_NAME), 'utf8'))
+		if (typeof manifest !== 'object' || manifest === null) return undefined
+		const { name } = manifest as { name?: unknown }
+
+		return typeof name === 'string' ? name : undefined
+	} catch {
+		// A missing, unreadable or malformed manifest says nothing about self-sync, and refusing to
+		// sync on it would break consumers whose manifest this package is about to create.
+		return undefined
+	}
+}
+
+function is_same_directory(first: string, second: string): boolean {
+	return path.resolve(first) === path.resolve(second)
+}
+
+// Is `inner` the same directory as `outer`, or somewhere beneath it? Asked in one direction only.
+// The reverse is the ordinary consumer layout — the package sits at
+// `<project>/node_modules/@joshuafolkken/kit`, so the PACKAGE directory is always inside the
+// PROJECT root — and refusing on that would refuse every sync there is.
+function is_within(inner: string, outer: string): boolean {
+	const relative = path.relative(path.resolve(outer), path.resolve(inner))
+
+	return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative))
+}
+
+// The name is the primary signal, not the path: game-kit's incident ran a GLOBAL install of the
+// package against its own repository, so `package_directory` and `project_root` were different
+// directories and a path comparison alone would have missed it.
+function name_reason(
+	package_name: string | undefined,
+	project_name: string | undefined,
+): string | undefined {
+	return package_name !== undefined && package_name === project_name
+		? `this is ${package_name}'s own repository`
+		: undefined
+}
+
+// Reached only when the project has no readable manifest to name it, which is the whole of what
+// makes containment usable here: a real consumer scaffolded under the checkout (a fixture at
+// `kit/tmp/consumer`) is nested too, and its manifest names it as something other than this package.
+// The nested case is `pnpm josh sync` run from `kit/docs`, where the sync would otherwise scatter a
+// consumer's worth of managed files inside the repository.
+function location_reason(package_directory: string, project_root: string): string | undefined {
+	if (is_same_directory(package_directory, project_root)) {
+		return 'the package directory and the project root are the same directory'
+	}
+
+	return is_within(project_root, package_directory)
+		? 'the project root is inside the package directory'
+		: undefined
+}
+
+function self_sync_reason(package_directory: string, project_root: string): string | undefined {
+	const project_name = read_package_name(project_root)
+	const by_name = name_reason(read_package_name(package_directory), project_name)
+
+	if (by_name !== undefined) return by_name
+
+	return project_name === undefined ? location_reason(package_directory, project_root) : undefined
+}
+
+// The message a sync prints before refusing. Phrased as what was detected plus what to do instead,
+// because the command is usually reached by habit ("re-sync after upgrading") and the user needs to
+// know nothing is wrong with their checkout.
+function self_sync_refusal(package_directory: string, project_root: string): string | undefined {
+	const reason = self_sync_reason(package_directory, project_root)
+
+	if (reason === undefined) return undefined
+
+	return [
+		`Refusing to sync: ${reason}.`,
+		'Syncing here would overwrite the distribution source with its own derived templates.',
+		'Run this command from a consumer project instead.',
+	].join('\n')
+}
+
+const self_sync_guard = { self_sync_reason, self_sync_refusal, read_package_name }
+
+export { self_sync_guard }

package/scripts/self-sync-guard/self-sync-refusal.ts

@@ -0,0 +1,22 @@
+import { self_sync_guard } from './self-sync-guard-logic'
+
+// The half of the guard that `sync` and `init` share verbatim: print the refusal and leave a
+// non-zero exit code. It lives beside the detection rather than in either entry point because the
+// two commands do the same damage in the source repository — `init` a larger share of it, since it
+// rewrites `package.json` scripts and devDependencies as well (joshuafolkken/kit#879) — and a copy
+// in each `main()` would be the second implementation the shared module exists to prevent.
+//
+// Not re-exported from `index.ts`: the published `@joshuafolkken/kit/self-sync-guard` surface stays
+// the pure detection, so a downstream distributor keeps deciding how its own CLI reports a refusal.
+function did_refuse_self_run(package_directory: string, project_root: string): boolean {
+	const refusal = self_sync_guard.self_sync_refusal(package_directory, project_root)
+
+	if (refusal === undefined) return false
+
+	console.error(`\n${refusal}\n`)
+	process.exitCode = 1
+
+	return true
+}
+
+export { did_refuse_self_run }