@joshuafolkken/kit 1.872.0

package/scripts/sync/skill-migration.ts

@@ -0,0 +1,192 @@
+import { createHash } from 'node:crypto'
+import { existsSync, lstatSync, readdirSync, readFileSync, rmSync } from 'node:fs'
+import path from 'node:path'
+import { transform_copied_content } from '#scripts/init/init-copy-content'
+import { is_transformable } from './directory-copy-guard'
+import { PLUGIN_SKILL_DIRECTORIES } from './plugin-skill-directories'
+
+// `josh sync` removes a consumer's stale copy of one of the plugin-distributed skill directories —
+// but only when the copy still matches what a fresh copy would have written. A copy the consumer
+// edited, or a skill the consumer authored under a name not on the distributed list, is left alone
+// and reported, because the managed marker the other migrations rely on is never written to a skill.
+
+type MigrationAction = 'removed' | 'kept' | 'absent'
+type MigrationSource = 'plugin' | 'retired'
+
+interface RemovedSkillFile {
+	readonly path: string
+	readonly sha256: string
+}
+
+interface RemovedSkill {
+	readonly directory: string
+	readonly files: ReadonlyArray<RemovedSkillFile>
+}
+
+type RemovedSkillManifest = ReadonlyArray<RemovedSkill>
+
+interface MigrationResult {
+	directory: string
+	action: MigrationAction
+	source: MigrationSource
+}
+
+// `lstatSync` rather than `statSync`: a consumer's skill directory can hold a dangling symlink, and
+// `statSync` follows it and throws `ENOENT`, which would abort the whole `josh sync` run uncaught —
+// the same reason `directory-copy-guard.ts` uses `lstat` throughout. A symlink then reads as
+// not-a-regular-file and is skipped, which correctly counts the tree as modified.
+function relative_files(root: string): Array<string> {
+	return readdirSync(root, { encoding: 'utf8', recursive: true }).filter((entry) =>
+		lstatSync(path.join(root, entry)).isFile(),
+	)
+}
+
+// What a fresh `josh sync` would have written for one file: markdown gets the copy transform (the
+// `prompts/…` rewrite and the rest), everything else is copied byte for byte. Comparing against this
+// is how an unmodified copy is told from one the consumer edited, with no marker to rely on.
+function expected_copy(source_file: string, destination_file: string): string {
+	const raw = readFileSync(source_file, 'utf8')
+
+	return is_transformable(source_file) ? transform_copied_content(destination_file, raw) : raw
+}
+
+function file_matches(source_root: string, destination_root: string, relative: string): boolean {
+	const destination_file = path.join(destination_root, relative)
+
+	if (!existsSync(destination_file)) return false
+
+	const source_file = path.join(source_root, relative)
+
+	return readFileSync(destination_file, 'utf8') === expected_copy(source_file, destination_file)
+}
+
+// Unmodified means the two trees hold the same set of files and every one matches. The count guard
+// catches a file the consumer added or deleted; `every` catches a file whose content was edited.
+function is_unmodified_copy(source_root: string, destination_root: string): boolean {
+	const sources = relative_files(source_root)
+
+	if (relative_files(destination_root).length !== sources.length) return false
+
+	return sources.every((relative) => file_matches(source_root, destination_root, relative))
+}
+
+function decide_action(source_root: string, destination_root: string): MigrationAction {
+	if (!existsSync(destination_root)) return 'absent'
+	// A vanished source means this is no longer one of kit's skills: leave the consumer's directory be.
+	if (!existsSync(source_root)) return 'kept'
+
+	return is_unmodified_copy(source_root, destination_root) ? 'removed' : 'kept'
+}
+
+function apply_action(
+	destination_root: string,
+	relative: string,
+	action: MigrationAction,
+	source: MigrationSource,
+): MigrationResult {
+	if (action === 'removed') rmSync(destination_root, { recursive: true, force: true })
+
+	return { directory: relative, action, source }
+}
+
+function migrate_directory(
+	package_root: string,
+	project_root: string,
+	relative: string,
+): MigrationResult {
+	const source_root = path.join(package_root, relative)
+	const destination_root = path.join(project_root, relative)
+	const action = decide_action(source_root, destination_root)
+
+	return apply_action(destination_root, relative, action, 'plugin')
+}
+
+function migrate_removed_skill_directories(
+	package_root: string,
+	project_root: string,
+): Array<MigrationResult> {
+	return PLUGIN_SKILL_DIRECTORIES.map((relative) =>
+		migrate_directory(package_root, project_root, relative),
+	)
+}
+
+function hash_content(content: string): string {
+	return createHash('sha256').update(content).digest('hex')
+}
+
+// The hashes a fresh copy of a retired skill's files produce, in path order. Built from a source tree
+// the same way `expected_copy` builds a comparison, then frozen into `removed-skill-manifest.ts`; the
+// manifest test recomputes this and fails on drift.
+function expected_manifest(source_root: string): Array<RemovedSkillFile> {
+	return relative_files(source_root)
+		.map((relative) => {
+			const file = path.join(source_root, relative)
+
+			return { path: relative, sha256: hash_content(expected_copy(file, file)) }
+		})
+		.toSorted((left, right) => left.path.localeCompare(right.path))
+}
+
+function manifest_file_matches(destination_root: string, file: RemovedSkillFile): boolean {
+	const destination_file = path.join(destination_root, file.path)
+
+	if (!existsSync(destination_file)) return false
+
+	return hash_content(readFileSync(destination_file, 'utf8')) === file.sha256
+}
+
+// A retired skill's copy is unmodified when the consumer's directory holds exactly the manifest's set
+// of files and every one hashes to its recorded value — the manifest counterpart of `is_unmodified_copy`.
+function matches_manifest(
+	destination_root: string,
+	files: ReadonlyArray<RemovedSkillFile>,
+): boolean {
+	if (relative_files(destination_root).length !== files.length) return false
+
+	return files.every((file) => manifest_file_matches(destination_root, file))
+}
+
+function decide_manifest_action(
+	destination_root: string,
+	files: ReadonlyArray<RemovedSkillFile>,
+): MigrationAction {
+	if (!existsSync(destination_root)) return 'absent'
+
+	return matches_manifest(destination_root, files) ? 'removed' : 'kept'
+}
+
+// The retired-skill counterpart of `migrate_removed_skill_directories`: a retired skill no longer
+// ships, so its copy is compared against the frozen manifest rather than a live package source.
+function migrate_manifest_skills(
+	project_root: string,
+	manifest: RemovedSkillManifest,
+): Array<MigrationResult> {
+	return manifest.map((skill) => {
+		const destination_root = path.join(project_root, skill.directory)
+		const action = decide_manifest_action(destination_root, skill.files)
+
+		return apply_action(destination_root, skill.directory, action, 'retired')
+	})
+}
+
+function removed_note(source: MigrationSource): string {
+	return source === 'retired' ? 'retired from distribution' : 'now provided by the kit plugin'
+}
+
+function kept_note(source: MigrationSource): string {
+	return source === 'retired'
+		? 'modified or consumer-authored — remove by hand'
+		: 'modified or consumer-authored — remove by hand once on the kit plugin'
+}
+
+const skill_migration = {
+	is_unmodified_copy,
+	migrate_removed_skill_directories,
+	migrate_manifest_skills,
+	expected_manifest,
+	removed_note,
+	kept_note,
+}
+
+export type { MigrationResult, RemovedSkillManifest }
+export { skill_migration }

package/scripts/sync/sync-configs.ts

@@ -0,0 +1,156 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { init_logic } from '#scripts/init/init-logic'
+import { PACKAGE_DIR } from '#scripts/init/init-paths'
+import { string_array_schema, vscode_settings_schema } from '#scripts/lib/schemas'
+
+type MergeFunction = (existing: string) => string
+
+const TSCONFIG_PRESET_DIR = 'tsconfig'
+const GITIGNORE_TEMPLATE_PATH = 'templates/gitignore'
+
+function sync_with_merge(
+	destination_path: string,
+	destination_name: string,
+	merge_function: MergeFunction,
+): void {
+	if (!existsSync(destination_path)) return
+
+	const existing = readFileSync(destination_path, 'utf8')
+	const merged = merge_function(existing)
+
+	if (merged === existing) {
+		console.info(`  ✔ unchanged ${destination_name}`)
+
+		return
+	}
+
+	writeFileSync(destination_path, merged)
+	console.info(`  ✔ synced    ${destination_name}`)
+}
+
+// Append-only, and deliberately so: a `_authToken` line in the consumer's file is left alone.
+// Sync used to remove the env-var form, which broke every project that had opted its project
+// .npmrc in via `npmrcAuthFile` — there the line is the live credential, and the opt-in itself
+// can live in a deploy platform's dashboard where sync cannot see it (joshuafolkken/kit#759).
+function sync_npmrc(destination_path: string): void {
+	sync_with_merge(destination_path, '.npmrc', init_logic.merge_npmrc)
+}
+
+// Union-merge kit's .gitignore entries into the consumer file instead of overwriting it,
+// so project-local ignore lines (e.g. an app's output dir) survive a sync.
+function sync_gitignore(destination_path: string): void {
+	const template = readFileSync(path.join(PACKAGE_DIR, GITIGNORE_TEMPLATE_PATH), 'utf8')
+
+	sync_with_merge(destination_path, '.gitignore', (existing) =>
+		init_logic.merge_gitignore(existing, template),
+	)
+}
+
+function sync_eslint_config(destination_path: string): void {
+	sync_with_merge(destination_path, 'eslint.config.js', (existing) =>
+		init_logic.merge_eslint_config(existing),
+	)
+}
+
+function read_base_compiler_options(): Record<string, unknown> {
+	const filename = init_logic.get_tsconfig_preset_filename()
+	const content = readFileSync(path.join(PACKAGE_DIR, TSCONFIG_PRESET_DIR, filename), 'utf8')
+
+	return init_logic.extract_compiler_options(content)
+}
+
+// Ensure the kit preset is in `extends`, drop any compilerOptions key whose value already equals
+// that preset — removing per-project drift while preserving genuine overrides — and union-merge the
+// generated-output directories into `exclude` so an existing consumer is repaired, not just a new one.
+function sync_tsconfig(destination_path: string): void {
+	const entry = init_logic.get_tsconfig_extends_entry()
+	const base_options = read_base_compiler_options()
+
+	const base_directory = path.dirname(destination_path)
+
+	sync_with_merge(destination_path, 'tsconfig.json', (existing) =>
+		init_logic.merge_tsconfig_exclude(
+			init_logic.strip_redundant_compiler_options(
+				init_logic.merge_tsconfig_extends(existing, entry, base_directory),
+				base_options,
+			),
+		),
+	)
+}
+
+function sync_cspell_config(destination_path: string): void {
+	const value = init_logic.get_cspell_import_value()
+
+	sync_with_merge(destination_path, 'cspell.config.yaml', (existing) =>
+		init_logic.merge_cspell_import(existing, value),
+	)
+}
+
+function sync_lefthook_config(destination_path: string): void {
+	const value = init_logic.get_lefthook_extends_value()
+
+	sync_with_merge(destination_path, 'lefthook.yml', (existing) =>
+		init_logic.merge_lefthook_extends(existing, value),
+	)
+}
+
+// Create-only, unlike the merge-based syncs above: once `.secretlintrc.json` exists its rule
+// list is project-owned (custom patterns, deliberate exclusions), so syncing must not rewrite
+// it. Projects initialized before the secretlint rule existed still get the file here.
+function sync_secretlint_config(destination_path: string): void {
+	if (existsSync(destination_path)) {
+		console.info('  ✔ unchanged .secretlintrc.json')
+
+		return
+	}
+
+	writeFileSync(destination_path, init_logic.generate_secretlint_config())
+	console.info('  ✔ created   .secretlintrc.json')
+}
+
+function read_kit_vscode_json(filename: string): unknown {
+	return JSON.parse(readFileSync(path.join(PACKAGE_DIR, '.vscode', filename), 'utf8'))
+}
+
+function read_vscode_recommendations(): ReadonlyArray<string> {
+	const parsed = vscode_settings_schema.parse(
+		read_kit_vscode_json(init_logic.VSCODE_EXTENSIONS_FILENAME),
+	)
+	const raw = parsed['recommendations']
+
+	return string_array_schema.parse(raw)
+}
+
+function sync_vscode_extensions_json(destination_path: string): void {
+	const recommendations = read_vscode_recommendations()
+
+	sync_with_merge(destination_path, '.vscode/extensions.json', (existing) =>
+		init_logic.merge_json_array_field(existing, 'recommendations', recommendations),
+	)
+}
+
+function sync_vscode_settings_json(destination_path: string): void {
+	const raw_settings = read_kit_vscode_json(init_logic.get_vscode_settings_filename())
+	const settings_data = init_logic.strip_kit_only_vscode_settings(
+		vscode_settings_schema.parse(raw_settings),
+	)
+
+	sync_with_merge(destination_path, '.vscode/settings.json', (existing) =>
+		init_logic.merge_json_object(existing, settings_data),
+	)
+}
+
+const sync_configs = {
+	sync_npmrc,
+	sync_gitignore,
+	sync_eslint_config,
+	sync_tsconfig,
+	sync_cspell_config,
+	sync_lefthook_config,
+	sync_secretlint_config,
+	sync_vscode_extensions_json,
+	sync_vscode_settings_json,
+}
+
+export { sync_configs }

package/scripts/sync/sync-hook-safety.ts

@@ -0,0 +1,82 @@
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { package_version_schema } from '#scripts/lib/schemas'
+import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
+import { safe_json_parse } from '#scripts/version/parse-json'
+import semver from 'semver'
+
+// `josh sync` writes the consumer's Claude and Codex hook files, whose hooks invoke bundles under
+// `node_modules/@joshuafolkken/kit/dist/` (joshuafolkken/kit#1930). When sync is run from a
+// newer source than the consumer's installed package — an `npx @joshuafolkken/kit sync`, or a global
+// josh — the settings it writes reference commands (e.g. `pretool:guard`) the older installed bundle
+// does not have, and every prompt then fails a hook that exits `Unknown command`
+// (joshuafolkken/kit#1930's own observation, kit 1.214). This checks the version before writing and
+// asks the consumer to update first rather than leaving broken hooks behind.
+//
+// Run through `pnpm josh sync` in the consumer the two versions are equal by construction — the same
+// install both writes the file and runs the hooks — so this never blocks the ordinary path.
+
+const NODE_MODULES = 'node_modules'
+
+function read_version_at(package_json_path: string): string | undefined {
+	if (!existsSync(package_json_path)) return undefined
+	const parsed = package_version_schema.safeParse(
+		safe_json_parse(readFileSync(package_json_path, 'utf8')),
+	)
+
+	return parsed.success ? parsed.data.version : undefined
+}
+
+// The version of kit installed in the consumer's node_modules — the bundle the rewritten hooks
+// actually run. Undefined before the first install, which is safe: a fresh install receives the
+// matching bundle, so there is nothing older to break.
+function installed_consumer_version(project_root: string): string | undefined {
+	return read_version_at(path.join(project_root, NODE_MODULES, KIT_PACKAGE_NAME, 'package.json'))
+}
+
+// Unsafe only when both versions are known AND the installed bundle the hooks run is older than the
+// version writing the settings. Either version unknown → safe: nothing can be asserted about a
+// mismatch, and refusing to write on a missing read would break a legitimate fresh sync.
+function is_safe_to_write_hooks(
+	writing_version: string | undefined,
+	installed_version: string | undefined,
+): boolean {
+	if (writing_version === undefined || installed_version === undefined) return true
+
+	return !semver.lt(installed_version, writing_version)
+}
+
+function outdated_install_warning(
+	writing_version: string,
+	installed_version: string,
+	filename: string,
+): string {
+	return (
+		`  ⚠ skipped   ${filename} — installed ${KIT_PACKAGE_NAME} is ${installed_version}, ` +
+		`older than the ${writing_version} writing it. Its hooks would call commands this install ` +
+		`cannot run. Run \`pnpm update ${KIT_PACKAGE_NAME}\` first, then \`pnpm josh sync\` again.`
+	)
+}
+
+// The one line to print and the reason to skip the hook file, or undefined when it is safe to write.
+function hook_write_warning(
+	project_root: string,
+	writing_version: string | undefined,
+	filename: string,
+): string | undefined {
+	const installed_version = installed_consumer_version(project_root)
+	if (writing_version === undefined || installed_version === undefined) return undefined
+	if (is_safe_to_write_hooks(writing_version, installed_version)) return undefined
+
+	return outdated_install_warning(writing_version, installed_version, filename)
+}
+
+const sync_hook_safety = {
+	hook_write_warning,
+	installed_consumer_version,
+	is_safe_to_write_hooks,
+	outdated_install_warning,
+	read_version_at,
+}
+
+export { sync_hook_safety }