@joshuafolkken/kit 1.872.0

package/scripts/sync/sync.ts

@@ -0,0 +1,417 @@
+#!/usr/bin/env tsx
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { gh_spawn } from '#scripts/gh/gh-spawn'
+import { transform_copied_content } from '#scripts/init/init-copy-content'
+import { init_logic } from '#scripts/init/init-logic'
+import { PACKAGE_DIR, PROJECT_ROOT } from '#scripts/init/init-paths'
+import { plugin_install_hint_module } from '#scripts/init/plugin-install-hint'
+import { auto_merge_setting } from '#scripts/repo/auto-merge-setting'
+import { security_updates } from '#scripts/security/security-updates'
+import { sonar_file } from '#scripts/security/sonar-file'
+import { did_refuse_self_run } from '#scripts/self-sync-guard/self-sync-refusal'
+import { package_manager_version } from '#scripts/version/package-manager-version'
+import { copy_directory_failure, directory_copy_blocker } from './directory-copy-guard'
+import { file_content } from './file-content'
+import { REMOVED_SKILL_MANIFEST } from './removed-skill-manifest'
+import { skill_migration, type MigrationResult } from './skill-migration'
+import { sync_configs } from './sync-configs'
+import { sync_hook_safety } from './sync-hook-safety'
+
+const WORKSPACE_YAML = 'pnpm-workspace.yaml'
+const PACKAGE_JSON = 'package.json'
+const PACKAGE_JSON_UNCHANGED_MSG = '  ✔ unchanged package.json'
+const CLAUDE_MD_FILENAME = 'CLAUDE.md'
+const CLAUDE_SETTINGS_FILE = '.claude/settings.json'
+const CODEX_HOOKS_FILE = '.codex/hooks.json'
+
+function sync_ai_file(source_path: string, destination_path: string): boolean {
+	const content = readFileSync(source_path, 'utf8')
+
+	return file_content.write_text_if_changed(
+		destination_path,
+		transform_copied_content(destination_path, content),
+	)
+}
+
+// Both copied hook files must run against the consumer's installed bundle. When sync is run from a
+// newer source than that install, writing either file would leave hooks
+// that fail every prompt (joshuafolkken/kit#1930); skip it and print how to update instead.
+function should_skip_hook_file(filename: string): boolean {
+	if (filename !== CLAUDE_SETTINGS_FILE && filename !== CODEX_HOOKS_FILE) return false
+	const warning = sync_hook_safety.hook_write_warning(
+		PROJECT_ROOT,
+		sync_hook_safety.read_version_at(path.join(PACKAGE_DIR, PACKAGE_JSON)),
+		filename,
+	)
+	if (warning === undefined) return false
+	console.warn(warning)
+
+	return true
+}
+
+function sync_file(filename: string): void {
+	if (should_skip_hook_file(filename)) return
+	const did_change = sync_ai_file(
+		path.join(PACKAGE_DIR, filename),
+		path.join(PROJECT_ROOT, filename),
+	)
+
+	console.info(`  ✔ ${did_change ? 'synced   ' : 'unchanged'} ${filename}`)
+}
+
+function sync_file_mapping(source_path: string, destination_path: string): void {
+	if (!existsSync(source_path)) {
+		console.warn(`  ⚠ skipped   ${path.basename(destination_path)} (not found in package)`)
+
+		return
+	}
+
+	// Routed through sync_ai_file rather than cpSync: templates/workflows/ci.yml is a mapped
+	// file, so a byte copy would hand the consumer the template's own action pins. The pins
+	// have to be resolved from .github/workflows at write time (joshuafolkken/kit#747).
+	const did_change = sync_ai_file(source_path, destination_path)
+
+	console.info(`  ✔ ${did_change ? 'synced   ' : 'unchanged'} ${path.basename(destination_path)}`)
+}
+
+function sync_workspace_yaml(
+	template_path: string,
+	destination_path: string,
+	is_force = false,
+): boolean {
+	const template = readFileSync(template_path, 'utf8')
+	const existing =
+		!is_force && existsSync(destination_path) ? readFileSync(destination_path, 'utf8') : ''
+	const merged = init_logic.merge_workspace_yaml(existing, template)
+
+	return file_content.write_text_if_changed(destination_path, merged)
+}
+
+function sync_ai_copy_file(filename: string, is_force: boolean): void {
+	if (filename === WORKSPACE_YAML) {
+		const did_change = sync_workspace_yaml(
+			path.join(PACKAGE_DIR, WORKSPACE_YAML),
+			path.join(PROJECT_ROOT, WORKSPACE_YAML),
+			is_force,
+		)
+
+		console.info(`  ✔ ${did_change ? 'synced   ' : 'unchanged'} ${WORKSPACE_YAML}`)
+
+		return
+	}
+
+	sync_file(filename)
+}
+
+// The reason this directory was not synced, or nothing when it was. Both halves answer the same
+// question — what stops the copy — so the caller has one line to print either way.
+function directory_sync_failure(
+	directory_name: string,
+	on_copy: (did_change: boolean) => void,
+): string | undefined {
+	const source_path = path.join(PACKAGE_DIR, directory_name)
+	const destination_path = path.join(PROJECT_ROOT, directory_name)
+
+	return (
+		directory_copy_blocker(source_path, destination_path) ??
+		copy_directory_failure(source_path, destination_path, on_copy)
+	)
+}
+
+function sync_directory(directory_name: string): void {
+	const failure = directory_sync_failure(directory_name, (did_change) => {
+		console.info(`  ✔ ${did_change ? 'synced   ' : 'unchanged'} ${directory_name}/`)
+	})
+
+	if (failure !== undefined) console.warn(`  ⚠ skipped   ${directory_name}/ (${failure})`)
+}
+
+function did_migrate_prettierrc(destination_path: string): boolean {
+	const legacy_path = path.join(path.dirname(destination_path), '.prettierrc')
+	if (!existsSync(legacy_path)) return false
+
+	const existing = readFileSync(legacy_path, 'utf8')
+
+	writeFileSync(destination_path, init_logic.merge_prettier_config(existing))
+	rmSync(legacy_path)
+
+	return true
+}
+
+function write_merged_prettier_config(destination_path: string): void {
+	const existing = readFileSync(destination_path, 'utf8')
+	const merged = init_logic.merge_prettier_config(existing)
+
+	if (merged === existing) {
+		console.info('  ✔ unchanged prettier.config.js')
+
+		return
+	}
+
+	writeFileSync(destination_path, merged)
+	console.info('  ✔ synced    prettier.config.js')
+}
+
+function sync_prettier_config(destination_path: string): void {
+	if (did_migrate_prettierrc(destination_path)) {
+		console.info('  ✔ migrated  .prettierrc → prettier.config.js')
+
+		return
+	}
+
+	if (!existsSync(destination_path)) return
+
+	write_merged_prettier_config(destination_path)
+}
+
+function sync_playwright_config(destination_path: string): void {
+	if (!existsSync(destination_path)) return
+
+	const template = init_logic.generate_playwright_config()
+	const existing = readFileSync(destination_path, 'utf8')
+
+	if (template === existing) {
+		console.info('  ✔ unchanged playwright.config.ts')
+
+		return
+	}
+
+	writeFileSync(destination_path, template)
+	console.info('  ✔ synced    playwright.config.ts')
+}
+
+function sync_deploy_vps(destination_path: string): void {
+	if (!existsSync(destination_path)) return
+
+	const existing = readFileSync(destination_path, 'utf8')
+	const patched = init_logic.patch_deploy_vps_pnpm(existing)
+
+	if (patched === existing) {
+		console.info('  ✔ unchanged deploy-vps.yml')
+
+		return
+	}
+
+	writeFileSync(destination_path, patched)
+	console.info('  ✔ synced    deploy-vps.yml')
+}
+
+function sync_sonar_with_template(name_with_owner: string | undefined, is_force = false): void {
+	const destination = init_logic.get_sonar_template_destination()
+
+	if (name_with_owner === undefined) {
+		console.warn(`  ⚠ skipped   ${destination} (gh repo view failed)`)
+
+		return
+	}
+
+	const template_source = path.join(PACKAGE_DIR, init_logic.get_sonar_template_source())
+	const identifiers = init_logic.derive_sonar_identifiers(name_with_owner)
+	const write_function = is_force ? sonar_file.write_sonar_file : sonar_file.merge_sonar_file
+
+	write_function(template_source, path.join(PROJECT_ROOT, destination), identifiers)
+	console.info(`  ✔ synced    ${destination}`)
+}
+
+// A consumer's stale copy of a distributed skill is removed once it still matches the shipment and
+// kept with a warning once it does not (joshuafolkken/kit#1879). Plugin skills compare against the
+// package source; a retired skill compares against the frozen manifest (joshuafolkken/kit#1990). The
+// note distinguishes the two, and `absent` — the consumer never had the copy — prints nothing.
+function report_migration_result(result: MigrationResult): void {
+	if (result.action === 'absent') return
+
+	if (result.action === 'removed') {
+		console.info(
+			`  ✔ removed   ${result.directory}/ (${skill_migration.removed_note(result.source)})`,
+		)
+
+		return
+	}
+
+	console.warn(`  ⚠ kept      ${result.directory}/ (${skill_migration.kept_note(result.source)})`)
+}
+
+function migrate_removed_skills(): void {
+	const plugin = skill_migration.migrate_removed_skill_directories(PACKAGE_DIR, PROJECT_ROOT)
+	const retired = skill_migration.migrate_manifest_skills(PROJECT_ROOT, REMOVED_SKILL_MANIFEST)
+
+	for (const result of [...plugin, ...retired]) report_migration_result(result)
+}
+
+// CLAUDE.md is not byte-copied (joshuafolkken/kit#1878): a consumer's file is one @import of kit's
+// published rules plus the project's own additions below it. Ensure the import line is present
+// without ever disturbing those additions — so this ignores --force, which would otherwise mean
+// discarding a consumer's content.
+function sync_claude_md(destination_path: string): void {
+	const existing = existsSync(destination_path) ? readFileSync(destination_path, 'utf8') : undefined
+	const ensured = init_logic.ensure_claude_md_import(existing)
+
+	if (ensured === existing) {
+		console.info(`  ✔ unchanged ${CLAUDE_MD_FILENAME}`)
+
+		return
+	}
+
+	mkdirSync(path.dirname(destination_path), { recursive: true })
+	writeFileSync(destination_path, ensured)
+	console.info(`  ✔ synced    ${CLAUDE_MD_FILENAME}`)
+}
+
+function sync_ai_copy_all(is_force: boolean): void {
+	console.info('AI files:')
+
+	sync_claude_md(path.join(PROJECT_ROOT, CLAUDE_MD_FILENAME))
+
+	for (const filename of init_logic.get_ai_copy_files()) {
+		sync_ai_copy_file(filename, is_force)
+	}
+
+	for (const { src, dest } of init_logic.get_ai_copy_file_mappings()) {
+		sync_file_mapping(path.join(PACKAGE_DIR, src), path.join(PROJECT_ROOT, dest))
+	}
+
+	for (const directory_name of init_logic.get_ai_copy_directories()) {
+		sync_directory(directory_name)
+	}
+
+	migrate_removed_skills()
+}
+
+function sync_config_files(): void {
+	sync_configs.sync_npmrc(path.join(PROJECT_ROOT, '.npmrc'))
+	sync_configs.sync_gitignore(path.join(PROJECT_ROOT, '.gitignore'))
+	sync_configs.sync_eslint_config(path.join(PROJECT_ROOT, 'eslint.config.js'))
+	sync_configs.sync_tsconfig(path.join(PROJECT_ROOT, 'tsconfig.json'))
+	sync_configs.sync_cspell_config(path.join(PROJECT_ROOT, 'cspell.config.yaml'))
+	sync_configs.sync_lefthook_config(path.join(PROJECT_ROOT, 'lefthook.yml'))
+	sync_configs.sync_secretlint_config(path.join(PROJECT_ROOT, '.secretlintrc.json'))
+	sync_configs.sync_vscode_extensions_json(path.join(PROJECT_ROOT, '.vscode/extensions.json'))
+	sync_configs.sync_vscode_settings_json(path.join(PROJECT_ROOT, '.vscode/settings.json'))
+}
+
+function sync_package_json_with(
+	destination_path: string,
+	transform: (existing: string) => string,
+	synced_message: string,
+): void {
+	if (!existsSync(destination_path)) return
+
+	const existing = readFileSync(destination_path, 'utf8')
+	const transformed = transform(existing)
+
+	if (transformed === existing) {
+		console.info(PACKAGE_JSON_UNCHANGED_MSG)
+
+		return
+	}
+
+	writeFileSync(destination_path, transformed)
+	console.info(synced_message)
+}
+
+// Repair an existing consumer manifest whose devEngines.packageManager.version
+// has drifted from its packageManager pin, so the pnpm dual-declaration warning
+// stays suppressed.
+function sync_package_manager_version(destination_path: string): void {
+	sync_package_json_with(
+		destination_path,
+		(existing) => package_manager_version.align_development_engines_version(existing),
+		'  ✔ synced    devEngines.packageManager.version',
+	)
+}
+
+// The pre-commit secretlint rule resolves secretlint from the consumer project, so a project
+// that predates the rule needs the devDependencies added here (then `pnpm install`) before the
+// hook can run. `josh init` covers fresh projects; this covers everyone already initialized.
+function sync_secretlint_development_deps(destination_path: string): void {
+	sync_package_json_with(
+		destination_path,
+		(existing) => init_logic.merge_secretlint_development_deps(existing),
+		'  ✔ synced    secretlint devDependencies (run `pnpm install`)',
+	)
+}
+
+// `lefthook install` fails silently when `core.hooksPath` is set, leaving a consumer with no hooks
+// and no message (joshuafolkken/kit#1503). `josh init` rewrites the clause it wrote so the failure
+// is reported; this covers everyone already initialized, who never re-runs `josh init`.
+function sync_prepare_lefthook_warning(destination_path: string): void {
+	sync_package_json_with(
+		destination_path,
+		(existing) => init_logic.upgrade_prepare_lefthook_warning(existing),
+		'  ✔ synced    prepare lefthook install warning (run `pnpm install`)',
+	)
+}
+
+// Every migration an already-initialized consumer needs applied to its own manifest, run as one
+// group so the next one is added here rather than at the call site.
+function sync_package_json_migrations(destination_path: string): void {
+	sync_package_manager_version(destination_path)
+	sync_secretlint_development_deps(destination_path)
+	sync_prepare_lefthook_warning(destination_path)
+}
+
+// Two distributed artifacts each depend on a repository setting kit cannot write, and both reports
+// are tied to the moment the artifact reaches the consumer. `.github/dependabot.yml` disables npm
+// version updates (joshuafolkken/kit#803), so a synced consumer only receives npm Dependabot pull
+// requests through the security-advisory path (joshuafolkken/kit#805);
+// `.github/workflows/dependabot-auto-merge.yml` runs `gh pr merge --auto`, which fails outright
+// unless the repository allows auto-merge (joshuafolkken/kit#834). Neither ever fails the sync: both
+// are GitHub-side state, not synced artifacts. Unconditional, unlike `init`, because `sync`
+// overwrites both files on every run.
+function report_repository_settings(name_with_owner: string | undefined): void {
+	security_updates.report_security_updates_section(name_with_owner)
+	auto_merge_setting.report_auto_merge_section(name_with_owner)
+}
+
+function sync_project_artifacts(is_force: boolean): void {
+	sync_ai_copy_all(is_force)
+	sync_prettier_config(path.join(PROJECT_ROOT, 'prettier.config.js'))
+	sync_playwright_config(path.join(PROJECT_ROOT, 'playwright.config.ts'))
+	sync_deploy_vps(path.join(PROJECT_ROOT, '.github/workflows/deploy-vps.yml'))
+	// Resolved where the Sonar sync has always needed it, and reused by the report below, so
+	// `gh repo view` runs once rather than twice. The position is the pre-existing one: the writes
+	// after this line already ran after the lookup before this change.
+	const name_with_owner = gh_spawn.get_repo_name_with_owner()
+
+	sync_sonar_with_template(name_with_owner, is_force)
+	sync_config_files()
+	sync_package_json_migrations(path.join(PROJECT_ROOT, PACKAGE_JSON))
+	report_repository_settings(name_with_owner)
+}
+
+// Checked before anything is written, never per file: the damage is the whole run, and a partial
+// sync that stopped halfway would leave the source repository in a state neither `git checkout` nor
+// a re-run describes (joshuafolkken/kit#868).
+function main(): void {
+	if (did_refuse_self_run(PACKAGE_DIR, PROJECT_ROOT)) return
+
+	const is_force = process.argv.includes('--force')
+
+	console.info('\n🔄 Syncing @joshuafolkken/kit AI files\n')
+	sync_project_artifacts(is_force)
+	plugin_install_hint_module.report_plugin_install_hint()
+	console.info('\n✅ Done.\n')
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main()
+
+const sync = {
+	should_skip_hook_file,
+	sync_file_mapping,
+	sync_ai_file,
+	sync_workspace_yaml,
+	sync_claude_md,
+	sync_prettier_config,
+	sync_playwright_config,
+	sync_deploy_vps,
+	sync_package_manager_version,
+	sync_secretlint_development_deps,
+	sync_prepare_lefthook_warning,
+	migrate_prettierrc: did_migrate_prettierrc,
+}
+
+// `sync` is the entry point; `sync_directory` and `main` are exported for their own unit tests, the
+// way `git-pr-checks.ts` exports the helpers beside its namespace.
+export { main, sync, sync_directory }

package/scripts/sync/synced-paths.ts

@@ -0,0 +1,52 @@
+import { init_logic } from '#scripts/init/init-logic'
+
+// **`josh sync` distributes more than the three `AI_COPY_*` lists**, and a gate that reads only
+// those is narrower than the instruction it replaced (joshuafolkken/kit#1578). The prose that
+// instruction lived in named `playwright.config.ts` as its own worked example — a file no `AI_COPY_*`
+// list holds — so a matcher built from those lists alone would have answered "not distributed" for
+// the very file the rule was written about.
+//
+// These are the consumer-root-relative destinations `sync_project_artifacts` and `sync_config_files`
+// write, in `scripts/sync/sync.ts`. `synced-paths.test.ts` reads that file and fails when a
+// destination appears there that is not listed here, so the two cannot drift apart the way a
+// hand-copied list would.
+
+// Written by `sync_project_artifacts` before it reaches the config files.
+const SYNCED_ARTIFACT_PATHS: ReadonlyArray<string> = [
+	'prettier.config.js',
+	'playwright.config.ts',
+	'.github/workflows/deploy-vps.yml',
+]
+
+// Written by `sync_config_files`, one call per entry.
+const SYNCED_CONFIG_PATHS: ReadonlyArray<string> = [
+	'.npmrc',
+	'.gitignore',
+	'eslint.config.js',
+	'tsconfig.json',
+	'cspell.config.yaml',
+	'lefthook.yml',
+	'.secretlintrc.json',
+	'.vscode/extensions.json',
+	'.vscode/settings.json',
+]
+
+// **`package.json` is deliberately absent.** `sync` does not overwrite it — it realigns one field,
+// `devEngines.packageManager.version`, with the `packageManager` pin. Listing it would fire the gate
+// on every dependency change in every repository, which is noise rather than a confirmation, and the
+// pin itself is already protected by its own prohibition in `CLAUDE.md`.
+const EXCLUDED_SYNC_TARGETS: ReadonlyArray<string> = ['package.json']
+
+// The Sonar destination is read from `init_logic` rather than repeated, because it is already a
+// single source there and `sync.ts` reaches it the same way.
+function get_synced_paths(): Array<string> {
+	return [
+		...SYNCED_ARTIFACT_PATHS,
+		...SYNCED_CONFIG_PATHS,
+		init_logic.get_sonar_template_destination(),
+	]
+}
+
+const synced_paths = { get_synced_paths }
+
+export { synced_paths, SYNCED_ARTIFACT_PATHS, SYNCED_CONFIG_PATHS, EXCLUDED_SYNC_TARGETS }

package/scripts/sync/template-source-logic.ts

@@ -0,0 +1,122 @@
+import { createHash } from 'node:crypto'
+import { copyFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { package_path } from '#scripts/init/init-paths'
+import { z } from 'zod'
+
+interface TemplateSourcePair {
+	template: string
+	source: string
+}
+
+// Internal maintainer guard state. Kept at the repo root (not under templates/)
+// so it is NOT distributed to consumers via the package `files` field, matching
+// the .overrides-snapshot.json convention. Holds tripwire-pair hashes only.
+const MANIFEST_PATH = '.template-source-manifest.json'
+
+// Copy pairs: the template is a byte-for-byte copy of the root source (no
+// intentional divergence). `reconcile` regenerates the copy; the parity test
+// asserts exact equality. npm strips a literal `.gitignore` from the package,
+// so the dotless `templates/gitignore` remains the distribution vehicle.
+const COPY_PAIRS: ReadonlyArray<TemplateSourcePair> = [
+	{ template: 'templates/gitignore', source: '.gitignore' },
+]
+
+// Tripwire pairs: the template intentionally diverges from the root source
+// (half of past source edits were deliberately not propagated). A source edit
+// trips the guard and forces a conscious re-check; propagation stays a human
+// decision. When adding a pair to either list, also add its `source` (and, for
+// copy pairs, its `template`) to the template-source-parity glob in lefthook.yml.
+const TRIPWIRE_PAIRS: ReadonlyArray<TemplateSourcePair> = [
+	{ template: 'templates/sonar-project.properties', source: 'sonar-project.properties' },
+]
+
+const source_manifest_schema = z.record(z.string(), z.string())
+
+type SourceManifest = z.infer<typeof source_manifest_schema>
+
+function read_file(relative_path: string): string {
+	return readFileSync(package_path(relative_path), 'utf8')
+}
+
+function read_optional_file(relative_path: string): string {
+	const full_path = package_path(relative_path)
+
+	return existsSync(full_path) ? readFileSync(full_path, 'utf8') : ''
+}
+
+function hash_text(text: string): string {
+	return createHash('sha256').update(text).digest('hex')
+}
+
+function find_copy_drift(): Array<TemplateSourcePair> {
+	return COPY_PAIRS.filter((pair) => read_optional_file(pair.template) !== read_file(pair.source))
+}
+
+function build_tripwire_manifest(): SourceManifest {
+	const manifest: SourceManifest = {}
+
+	for (const pair of TRIPWIRE_PAIRS) {
+		manifest[pair.source] = hash_text(read_file(pair.source))
+	}
+
+	return manifest
+}
+
+function find_tripwire_drift(recorded: SourceManifest): Array<TemplateSourcePair> {
+	return TRIPWIRE_PAIRS.filter(
+		(pair) => recorded[pair.source] !== hash_text(read_file(pair.source)),
+	)
+}
+
+function read_recorded_manifest(): SourceManifest {
+	return source_manifest_schema.parse(JSON.parse(read_file(MANIFEST_PATH)))
+}
+
+function format_drift_message(
+	copy_drift: ReadonlyArray<TemplateSourcePair>,
+	tripwire_drift: ReadonlyArray<TemplateSourcePair>,
+): string {
+	const lines = [
+		...copy_drift.map((pair) => `  - ${pair.template} is out of date with ${pair.source}`),
+		...tripwire_drift.map((pair) => `  - ${pair.source} changed → review ${pair.template}`),
+	]
+
+	return [
+		'✖ Template source(s) need reconciling:',
+		...lines,
+		'  Review any tripwire template, then run `pnpm josh reconcile-templates`.',
+	].join('\n')
+}
+
+function regenerate_copies(): void {
+	for (const pair of COPY_PAIRS) {
+		copyFileSync(package_path(pair.source), package_path(pair.template))
+	}
+}
+
+function write_tripwire_manifest(): void {
+	const serialized = `${JSON.stringify(build_tripwire_manifest(), undefined, '\t')}\n`
+
+	writeFileSync(package_path(MANIFEST_PATH), serialized)
+}
+
+function reconcile(): void {
+	regenerate_copies()
+	write_tripwire_manifest()
+}
+
+const template_source_logic = {
+	MANIFEST_PATH,
+	COPY_PAIRS,
+	TRIPWIRE_PAIRS,
+	hash_text,
+	find_copy_drift,
+	build_tripwire_manifest,
+	find_tripwire_drift,
+	read_recorded_manifest,
+	format_drift_message,
+	reconcile,
+}
+
+export { template_source_logic, source_manifest_schema }
+export type { SourceManifest, TemplateSourcePair }