@joshuafolkken/kit 1.872.0

package/scripts/sync/directory-copy-guard.ts

@@ -0,0 +1,187 @@
+import { cpSync, lstatSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { transform_copied_content } from '#scripts/init/init-copy-content'
+import { file_content } from './file-content'
+
+// `josh init` and `josh sync` both copy a distributed directory with `cpSync`, and both have to
+// answer the same question first: is this copy one that `cpSync` will refuse? The answer lives here
+// rather than in each command, because the failure modes are the same and a second copy of the list
+// would drift (joshuafolkken/kit#853, which made the directory list non-empty for the first time).
+//
+// Every check goes through `lstat`, never `existsSync` or `stat`:
+//   - `stat` follows a symlink, so a link pointing at a directory would read as a directory while
+//     `cpSync` — which compares with `lstat` — throws ERR_FS_CP_DIR_TO_NON_DIR on it;
+//   - `existsSync` is false for a broken link, and `cpSync` does not merely throw on one: it ends
+//     the process with an uncaught filesystem error, which no caller can report or recover from.
+type DestinationKind = 'absent' | 'directory' | 'other'
+
+// Only "there is nothing here" reads as absent, which is ENOENT and nothing else. A permission error
+// says the opposite — something is there and cannot be inspected — and ENOTDIR says a component of
+// the path is a file, which is also something rather than nothing. Reading either as absent would
+// send the caller into the `cpSync` that then throws uncaught, the abort this module exists to stop.
+const ABSENT_CODE = 'ENOENT'
+
+function error_code_of(error: unknown): string {
+	return error instanceof Error && 'code' in error ? String(error.code) : ''
+}
+
+function classify_path(candidate_path: string): DestinationKind {
+	try {
+		return lstatSync(candidate_path).isDirectory() ? 'directory' : 'other'
+	} catch (error) {
+		return error_code_of(error) === ABSENT_CODE ? 'absent' : 'other'
+	}
+}
+
+// The reason this copy cannot run, or nothing when it can. Phrased for the console line each command
+// prints, so a skip always says which of the cases it was.
+function directory_copy_blocker(source_path: string, destination_path: string): string | undefined {
+	if (classify_path(source_path) !== 'directory') return 'missing from the installed package'
+
+	if (path.resolve(source_path) === path.resolve(destination_path)) {
+		return "already the package's own copy"
+	}
+
+	return classify_path(destination_path) === 'other' ? 'destination is not a directory' : undefined
+}
+
+// `cpSync` copies bytes, so a distributed directory would otherwise carry the package's own
+// `prompts/…` references into a consumer, where that directory does not exist — the very rewrite
+// every file copy already runs through `transform_copied_content`. Running it over the copied tree
+// puts both copy paths on one transform, which is what lets a skill cite the prompt it extends
+// (joshuafolkken/kit#854).
+//
+// Markdown only, and deliberately so: the rewrite is a text substitution, the workflow pin and
+// managed-marker passes inside `transform_copied_content` are gated on a `.github/workflows`
+// destination and so are no-ops here, and a binary payload run through a utf8 round-trip would be
+// corrupted rather than left alone.
+const TRANSFORMED_EXTENSION = '.md'
+
+// A `.md` name is not on its own a file to rewrite: a directory or a symlink can carry the suffix,
+// and `readFileSync` answers the first with EISDIR and follows the second out of the tree. Both are
+// classified before the read rather than caught after it, so a stray entry is skipped instead of
+// failing the copy it sits in.
+// `lstat` rather than `classify_path`: that one answers "is this a directory", because its callers
+// ask about a copy destination, and widening its result would silently loosen the guard that reads
+// `'other'` as "refuse". This asks the opposite question and keeps its own answer.
+function is_regular_file(candidate_path: string): boolean {
+	try {
+		return lstatSync(candidate_path).isFile()
+	} catch {
+		return false
+	}
+}
+
+function is_transformable(candidate_path: string): boolean {
+	return candidate_path.endsWith(TRANSFORMED_EXTENSION) && is_regular_file(candidate_path)
+}
+
+function transform_copied_file(file_path: string): void {
+	const content = readFileSync(file_path, 'utf8')
+	const transformed = transform_copied_content(file_path, content)
+	if (transformed !== content) writeFileSync(file_path, transformed)
+}
+
+// The walk reads the SOURCE listing and rewrites the matching destination paths, never the
+// destination's own listing. The copy merges rather than prunes, so a consumer's own notes sit
+// beside the distributed files — walking the destination would rewrite those too, silently editing
+// text this package never wrote. Only what was just copied is ours to touch.
+function transform_copied_tree(source_path: string, destination_path: string): void {
+	const entries = readdirSync(source_path, { encoding: 'utf8', recursive: true })
+
+	for (const entry of entries) {
+		if (!is_transformable(path.join(source_path, entry))) continue
+
+		transform_copied_file(path.join(destination_path, entry))
+	}
+}
+
+function should_copy_entry(source_path: string, destination_path: string): boolean {
+	if (!is_regular_file(source_path)) return true
+
+	if (classify_path(destination_path) === 'directory') {
+		throw new Error('destination is a directory where the package has a file')
+	}
+
+	const source_content = readFileSync(source_path)
+	const content = source_path.endsWith(TRANSFORMED_EXTENSION)
+		? transform_copied_content(destination_path, source_content.toString('utf8'))
+		: source_content
+
+	return !file_content.is_same_file_content(destination_path, content)
+}
+
+function is_changed_entry(source_entry: string, destination_entry: string, root: string): boolean {
+	if (source_entry === root) return false
+	if (is_regular_file(source_entry)) return true
+
+	return classify_path(destination_entry) === 'absent'
+}
+
+function copy_directory(source_path: string, destination_path: string): boolean {
+	let did_change = false
+
+	cpSync(source_path, destination_path, {
+		recursive: true,
+		filter: (source_entry, destination_entry) => {
+			const should_copy = should_copy_entry(source_entry, destination_entry)
+
+			if (should_copy && is_changed_entry(source_entry, destination_entry, source_path)) {
+				did_change = true
+			}
+
+			return should_copy
+		},
+	})
+
+	return did_change
+}
+
+// The guards above answer what can be known before the copy; this one answers what the copy itself
+// runs into. `cpSync` walks the whole tree, so a type conflict nested inside it — a consumer
+// directory where the package has a file — throws only once the walk reaches it, and an uncaught
+// throw here would end `josh init` or `josh sync` in the middle of their work. The message is
+// returned for the caller to report, the same way a blocker is.
+function failure_message(prefix: string, error: unknown): string {
+	return `${prefix} (${error instanceof Error ? error.message : String(error)})`
+}
+
+// The two failures are reported apart because they leave the destination in opposite states, and
+// the callers print the message as the reason a directory was skipped. A `cpSync` throw means the
+// copy did not finish, which "skipped" describes; a rewrite throw means the copy DID finish and the
+// tree was replaced, with some files still citing the package's own `prompts/…` paths. Reporting
+// that one as "skipped" would tell the user nothing was written while everything was — so it says
+// the directory was replaced and names the fix, which is to run the sync again once the cause of
+// the read or write error is gone. There is no rollback: a temp-directory swap would not survive
+// the permission and I/O errors that are the realistic throws here either.
+function copy_directory_failure(
+	source_path: string,
+	destination_path: string,
+	on_copy?: (did_change: boolean) => void,
+): string | undefined {
+	let did_change = false
+
+	try {
+		did_change ||= copy_directory(source_path, destination_path)
+	} catch (error) {
+		return failure_message('copy failed', error)
+	}
+
+	try {
+		transform_copied_tree(source_path, destination_path)
+	} catch (error) {
+		return failure_message('copied but left partly un-rewritten — re-run the sync', error)
+	}
+
+	on_copy?.(did_change)
+
+	return undefined
+}
+
+export {
+	classify_path,
+	copy_directory_failure,
+	directory_copy_blocker,
+	is_transformable,
+	transform_copied_tree,
+}

package/scripts/sync/file-content.ts

@@ -0,0 +1,49 @@
+import { lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+
+function is_absent_error(error: unknown): boolean {
+	return error instanceof Error && 'code' in error && error.code === 'ENOENT'
+}
+
+function is_read_denied(error: unknown): boolean {
+	return (
+		error instanceof Error && 'code' in error && ['EACCES', 'EPERM'].includes(String(error.code))
+	)
+}
+
+function is_regular_existing_file(destination_path: string): boolean {
+	try {
+		return lstatSync(destination_path).isFile()
+	} catch (error) {
+		if (is_absent_error(error)) return false
+		throw error
+	}
+}
+
+function does_read_match(destination_path: string, expected: Buffer): boolean {
+	try {
+		return readFileSync(destination_path).equals(expected)
+	} catch (error) {
+		if (is_read_denied(error)) return false
+		throw error
+	}
+}
+
+function is_same_file_content(destination_path: string, content: string | Buffer): boolean {
+	if (!is_regular_existing_file(destination_path)) return false
+
+	const expected = Buffer.isBuffer(content) ? content : Buffer.from(content)
+
+	return does_read_match(destination_path, expected)
+}
+
+function write_text_if_changed(destination_path: string, content: string): boolean {
+	if (is_same_file_content(destination_path, content)) return false
+
+	mkdirSync(path.dirname(destination_path), { recursive: true })
+	writeFileSync(destination_path, content)
+
+	return true
+}
+
+export const file_content = { is_same_file_content, write_text_if_changed }

package/scripts/sync/managed-config-scope-cli.ts

@@ -0,0 +1,64 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { path_decision } from '#scripts/josh/path-decision'
+import { managed_config_scope } from './managed-config-scope'
+
+// `josh sync:scope` — say whether this change touches a file `josh sync` distributes
+// (joshuafolkken/kit#1578).
+//
+// A command rather than a paragraph, for the reason `josh review:level` is one: the confirmation
+// stop this feeds was written as an instruction to compare the diff against three arrays by eye, and
+// on the day it was measured two runs in three did not make the comparison at all. `AI_COPY_DIRECTORIES`
+// is why an eye comparison cannot be relied on even when it is made — a distributed path need not
+// appear in any list textually, so the reader is solving a prefix match by hand.
+//
+// Everything but the question itself — reading the changed paths, the flags, the printing — is
+// `path_decision`'s, shared with `josh review:level`, which asks a different question of the same
+// tree.
+
+const ARGV_OFFSET = 2
+const USAGE = 'Usage: josh sync:scope [--staged] [--json]'
+const JSON_KEY = 'scope'
+
+const MANAGED_ANSWER = 'managed'
+const CLEAN_ANSWER = 'clean'
+
+type SyncScope = typeof MANAGED_ANSWER | typeof CLEAN_ANSWER
+
+function decide(paths: ReadonlyArray<string>): SyncScope {
+	return managed_config_scope.has_managed_path(paths) ? MANAGED_ANSWER : CLEAN_ANSWER
+}
+
+// The reason names the list beside each path, because that is the half a reader cannot derive: a
+// path claimed by `AI_COPY_DIRECTORIES` matches no entry textually. The truncation is
+// `path_decision`'s own, so a large diff prints a reason rather than a wall.
+function format_reason(paths: ReadonlyArray<string>, answer: SyncScope): string {
+	if (answer === CLEAN_ANSWER) return 'no changed path is distributed by josh sync'
+
+	const hits = managed_config_scope.find_managed_paths(paths)
+	const listed = hits.map((hit) => managed_config_scope.format_hit(hit))
+
+	return `distributed paths in this change: ${path_decision.format_path_list(listed)}`
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	return await path_decision.run_path_decision(argv, {
+		usage: USAGE,
+		key: JSON_KEY,
+		decide,
+		explain: format_reason,
+	})
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const managed_config_scope_cli = { decide, format_reason, JSON_KEY, main, run, USAGE }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+// The two answers are named exports rather than members of the object above: read off a plain object
+// literal they widen to `string`, and a caller comparing against them then type-checks against any
+// string at all. Constants are exempt from the namespace grouping convention for this reason.
+export { managed_config_scope_cli, MANAGED_ANSWER, CLEAN_ANSWER }

package/scripts/sync/managed-config-scope.ts

@@ -0,0 +1,123 @@
+import { init_logic } from '#scripts/init/init-logic'
+import { PLUGIN_SKILL_DIRECTORIES } from './plugin-skill-directories'
+import { synced_paths } from './synced-paths'
+
+// The three lists `josh sync` distributes from, spelled exactly as they are declared in
+// `scripts/init/init-logic.ts`. The answer has to name which list claimed a path, and a paraphrase
+// would send the reader looking for a constant that does not exist.
+const AI_COPY_FILES_LIST = 'AI_COPY_FILES'
+const AI_COPY_FILE_MAPPINGS_LIST = 'AI_COPY_FILE_MAPPINGS'
+const AI_COPY_DIRECTORIES_LIST = 'AI_COPY_DIRECTORIES'
+
+// The fourth source, named for the module that enumerates it rather than for an array in
+// `init-logic.ts`: these destinations are written by `sync.ts` directly and appear on no list there.
+const SYNCED_PATHS_LIST = 'SYNCED_PATHS'
+
+// The fifth source: the skill directories that ship as the `kit` plugin rather than as a copy
+// (joshuafolkken/kit#1879). They are no longer in `AI_COPY_DIRECTORIES`, but a change to one still
+// reaches consumers through the package, so the gate keeps flagging it.
+const PLUGIN_SKILL_DIRECTORIES_LIST = 'PLUGIN_SKILL_DIRECTORIES'
+
+const PATH_SEPARATOR = '/'
+
+interface ManagedHit {
+	path: string
+	list: string
+}
+
+// A directory entry carries no trailing separator, so a bare `startsWith` would also claim a sibling
+// whose name merely begins with it — `.claude/skills/workflow-commands-x/a.md` against
+// `.claude/skills/workflow-commands`. Appending the separator is what makes this a containment test
+// rather than a prefix test.
+function is_inside(path: string, directory: string): boolean {
+	return path === directory || path.startsWith(`${directory}${PATH_SEPARATOR}`)
+}
+
+function matches_file(path: string): boolean {
+	return init_logic.get_ai_copy_files().includes(path)
+}
+
+// **Both ends of a mapping count.** `src` is this repository's own template path and `dest` is where
+// the consumer receives the same file, so a change made here is caught by `src` and one read against
+// a consumer checkout is caught by `dest`. Matching only one end would leave the other silent, which
+// is the failure this whole module exists to remove.
+function matches_mapping(path: string): boolean {
+	return init_logic
+		.get_ai_copy_file_mappings()
+		.some((mapping) => mapping.src === path || mapping.dest === path)
+}
+
+function matches_directory(path: string): boolean {
+	return init_logic.get_ai_copy_directories().some((directory) => is_inside(path, directory))
+}
+
+function matches_plugin_skill(path: string): boolean {
+	return PLUGIN_SKILL_DIRECTORIES.some((directory) => is_inside(path, directory))
+}
+
+// The paths `josh sync` writes outside the three `AI_COPY_*` lists — `playwright.config.ts` and the
+// rest. Reading only those three made the gate **narrower than the instruction it replaced**, whose
+// own worked example was a file none of them holds (joshuafolkken/kit#1578).
+function matches_synced_path(path: string): boolean {
+	return synced_paths.get_synced_paths().includes(path)
+}
+
+// A table rather than a chain of `if`s: a fifth distribution surface is then one row, and the search
+// order stays visible in one place. The sources are searched top to bottom and the first to claim the
+// path wins — a path on two is reported once, because naming the second changes nothing the reader
+// does and a second row per path would make the count of hits disagree with the count of files.
+const MATCHERS: ReadonlyArray<{ list: string; matches: (path: string) => boolean }> = [
+	{ list: AI_COPY_FILES_LIST, matches: matches_file },
+	{ list: AI_COPY_FILE_MAPPINGS_LIST, matches: matches_mapping },
+	{ list: AI_COPY_DIRECTORIES_LIST, matches: matches_directory },
+	{ list: PLUGIN_SKILL_DIRECTORIES_LIST, matches: matches_plugin_skill },
+	{ list: SYNCED_PATHS_LIST, matches: matches_synced_path },
+]
+
+function find_list(path: string): string | undefined {
+	return MATCHERS.find((matcher) => matcher.matches(path))?.list
+}
+
+function to_hit(path: string): ManagedHit | undefined {
+	const list = find_list(path)
+
+	return list === undefined ? undefined : { path, list }
+}
+
+// One hit per path, in the order the paths arrived, so the output reads in the same order as the
+// diff that produced it.
+function find_managed_paths(paths: ReadonlyArray<string>): Array<ManagedHit> {
+	return paths.flatMap((path) => to_hit(path) ?? [])
+}
+
+function has_managed_path(paths: ReadonlyArray<string>): boolean {
+	return paths.some((path) => find_list(path) !== undefined)
+}
+
+// The path *and* the list that claimed it, because the two answer different questions: which file to
+// look at, and why it counts as distributed. `AI_COPY_DIRECTORIES` is the one a reader cannot derive
+// by eye — the path matched a directory entry it does not textually equal (joshuafolkken/kit#1578).
+function format_hit(hit: ManagedHit): string {
+	return `${hit.path} (${hit.list})`
+}
+
+function format_hits(hits: ReadonlyArray<ManagedHit>): string {
+	return hits.map((hit) => format_hit(hit)).join('\n')
+}
+
+const managed_config_scope = {
+	find_managed_paths,
+	has_managed_path,
+	format_hit,
+	format_hits,
+}
+
+export {
+	managed_config_scope,
+	AI_COPY_FILES_LIST,
+	AI_COPY_FILE_MAPPINGS_LIST,
+	AI_COPY_DIRECTORIES_LIST,
+	PLUGIN_SKILL_DIRECTORIES_LIST,
+	SYNCED_PATHS_LIST,
+}
+export type { ManagedHit }

package/scripts/sync/plugin-skill-directories.ts

@@ -0,0 +1,15 @@
+// The skill directories kit ships as the `kit` Claude Code plugin (joshuafolkken/kit#1879). A
+// consumer receives them through the plugin rather than as a copy, so this is the single source two
+// places read: `skill-migration.ts` removes a consumer's stale copy of one, and
+// `managed-config-scope.ts` flags a change to one as reaching consumers. It is deliberately separate
+// from `init-logic.ts`'s `AI_COPY_DIRECTORIES` — which is now empty — because these directories are
+// distributed but no longer copied. `diag` is deliberately absent: it drives kit's own run
+// measurement, so it is excluded from the package and the plugin (joshuafolkken/kit#1997).
+const PLUGIN_SKILL_DIRECTORIES: ReadonlyArray<string> = [
+	'.claude/skills/workflow-commands',
+	'.claude/skills/epic-commands',
+	'.claude/skills/dependency-update',
+	'.claude/skills/verify-ui',
+]
+
+export { PLUGIN_SKILL_DIRECTORIES }

package/scripts/sync/reconcile-templates.ts

@@ -0,0 +1,53 @@
+#!/usr/bin/env tsx
+/**
+ * Reconcile (or check) distributed templates against their root sources.
+ *
+ * Usage:
+ *   tsx scripts/sync/reconcile-templates.ts            # regenerate copy templates + record tripwire hashes
+ *   tsx scripts/sync/reconcile-templates.ts --check    # verify templates are in sync; non-zero on drift
+ *
+ * Copy pairs (e.g. .gitignore → templates/gitignore) are byte-for-byte copies,
+ * regenerated automatically. Tripwire pairs (e.g. sonar-project.properties)
+ * intentionally diverge: a source edit trips --check until the paired template
+ * is reviewed and reconciled. Only the review is enforced for tripwire pairs.
+ */
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+import { template_source_logic } from './template-source-logic'
+
+function check_drift(): never {
+	const copy_drift = template_source_logic.find_copy_drift()
+	const tripwire_drift = template_source_logic.find_tripwire_drift(
+		template_source_logic.read_recorded_manifest(),
+	)
+
+	if (copy_drift.length + tripwire_drift.length > 0) {
+		console.error(template_source_logic.format_drift_message(copy_drift, tripwire_drift))
+		process.exit(1)
+	}
+
+	console.info('✔ Templates are in sync with their sources.')
+	process.exit(0)
+}
+
+function reconcile(): never {
+	template_source_logic.reconcile()
+	console.info(
+		`✔ Templates reconciled (copies regenerated; ${template_source_logic.MANIFEST_PATH} updated).`,
+	)
+	process.exit(0)
+}
+
+function main(): void {
+	const { values } = parseArgs({
+		options: { check: { type: 'boolean', default: false } },
+		strict: true,
+	})
+
+	if (values.check) check_drift()
+	reconcile()
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main()
+
+export { check_drift, reconcile }

package/scripts/sync/removed-skill-manifest.ts

@@ -0,0 +1,27 @@
+import type { RemovedSkillManifest } from './skill-migration'
+
+// Skill directories kit once distributed but has since retired. Unlike PLUGIN_SKILL_DIRECTORIES, a
+// retired skill's source no longer ships in the package, so `josh sync` cannot byte-compare a
+// consumer's stale copy against a live source. It compares against these hashes instead — the sha256
+// of each file's distributed (path-transformed) content, which is consumer-independent, so one hash
+// matches every consumer's untouched copy while an edited copy no longer matches and is kept.
+//
+// `diag` was dropped from distribution in joshuafolkken/kit#1997 because it drives kit's own run
+// measurement, and its source was deleted in joshuafolkken/kit#2015; this removes the copy a consumer
+// received before then (joshuafolkken/kit#1990). `removed-skill-manifest.test.ts` recomputes these
+// from the repo's own skill source and fails on drift where that source still ships; an entry whose
+// source has since been deleted has nothing left to recompute against, so its frozen hashes stand as
+// the permanent distributed record, guarded only by the test's well-formed-sha256 shape check.
+const REMOVED_SKILL_MANIFEST: RemovedSkillManifest = [
+	{
+		directory: '.claude/skills/diag',
+		files: [
+			{
+				path: 'SKILL.md',
+				sha256: '16e5399859fdb99033350ec41c147adf4422f2a76de88ecdfc877c4a24ab7510',
+			},
+		],
+	},
+]
+
+export { REMOVED_SKILL_MANIFEST }