@joshuafolkken/kit 1.1387.0 → 1.1453.0

package/scripts/git/git-command.ts

@@ -166,14 +166,25 @@ async function delete_branch(branch_name: string): Promise<void> {
 // report "nothing is stranded" about a branch nobody measured, which is the one wrong answer that
 // loses work. `count_merges` guards the same way and falls back to `0` instead, because there a
 // missing count means an empty range rather than a claim about somebody's commits.
-async function commit_count_beyond(base: string, tip: string): Promise<number> {
-	const range = `${base}..${tip}`
-	const output = await git_spawn.read(['rev-list', '--count', range])
+async function read_commit_count(revisions: ReadonlyArray<string>): Promise<number> {
+	const output = await git_spawn.read(['rev-list', '--count', ...revisions])
 	const parsed = Number(output)
 
 	if (output.length > 0 && Number.isFinite(parsed)) return parsed
 
-	throw new Error(`\`git rev-list --count ${range}\` printed \`${output}\` rather than a count`)
+	throw new Error(
+		`\`git rev-list --count ${revisions.join(' ')}\` printed \`${output}\` rather than a count`,
+	)
+}
+
+async function commit_count_beyond(base: string, tip: string): Promise<number> {
+	return await read_commit_count([`${base}..${tip}`])
+}
+
+// How many commits `branch_name` holds that no remote-tracking ref reaches — what deleting the branch
+// would lose. An unparseable count throws for the reason `commit_count_beyond`'s does.
+async function commit_count_unpushed(branch_name: string): Promise<number> {
+	return await read_commit_count([branch_name, '--not', '--remotes'])
 }
 
 function is_exit_code_128(cause: unknown): boolean {
@@ -397,6 +408,7 @@ const git_command = {
 	checkout,
 	commit,
 	commit_count_beyond,
+	commit_count_unpushed,
 	delete_branch,
 	push,
 	pull_fast_forward,

package/scripts/git/git-schemas.ts

@@ -10,6 +10,7 @@ const rollup_item_schema = z.looseObject({
 	conclusion: z.string().optional(),
 	name: z.string().optional(),
 	context: z.string().optional(),
+	description: z.string().nullish(),
 })
 
 const pr_raw_schema = z.object({

package/scripts/git/git-spawn-sync.ts

@@ -72,4 +72,4 @@ function toplevel(timeout: number = GIT_TIMEOUT_MS): GitSyncResult {
 const git_spawn_sync = { GIT_TIMEOUT_MS, C_LOCALE, run, read, origin_url, toplevel }
 
 export { git_spawn_sync }
-export type { GitSyncResult }
+export type { GitSyncOptions, GitSyncResult }

package/scripts/hooks/pretool-guard.ts

@@ -1,5 +1,6 @@
 import { duplicate_read_outcome } from '#scripts/delegation/duplicate-read-guard'
 import { investigation_refusal } from '#scripts/delegation/investigation-guard'
+import { issue_watch_hook } from '#scripts/issue/issue-watch-hook'
 import { hook_decision, type GuardOutcome } from '#scripts/josh/hook-decision'
 import { lane_phase } from '#scripts/lane/lane-phase'
 import { json_value } from '#scripts/lib/json-value'
@@ -104,8 +105,9 @@ async function mark_phase(outcome: GuardOutcome): Promise<void> {
 // surfaced first.
 async function async_reason(raw_payload: string): Promise<string | undefined> {
 	const watcher = await run_watcher_hook.watcher_hook_reason(raw_payload)
+	const cut = watcher ?? (await run_parent_cut_hook.parent_cut_reason(raw_payload))
 
-	return watcher ?? (await run_parent_cut_hook.parent_cut_reason(raw_payload))
+	return cut ?? (await issue_watch_hook.watch_reason())
 }
 
 async function pretool_outcome_async(raw_payload: string): Promise<GuardOutcome> {

package/scripts/init/hook-command-rewrite.ts

@@ -25,6 +25,30 @@ const CONSUMER_PACKAGE_MANIFEST = `${claude_plugin_config.MARKETPLACE_PATH}/pack
 const MISSING_INSTALL_NOTICE = 'kit hooks inactive: run pnpm install, then reread CLAUDE.md'
 const MISSING_INSTALL_GUARD = `if [ ! -f ${CONSUMER_PACKAGE_MANIFEST} ]; then echo '${MISSING_INSTALL_NOTICE}' >&2; exit 0; fi; `
 const CODEX_HOOKS_DESTINATION = '.codex/hooks.json'
+// Every shape a hook command kit wrote can carry: the launcher as kit's own file names it, the
+// launcher rebased onto the installed package, and the installed dispatcher the releases from
+// 2026-09-13 (joshuafolkken/kit#1930) to the launcher rebased `pnpm josh` onto. The settings merge
+// tells kit's hooks from a project's own by these and the list below, so the shapes stay beside the
+// rewrite that produces them.
+const KIT_COMMAND_MARKERS: ReadonlyArray<string> = [
+	RUN_HOOK_INVOCATION,
+	CONSUMER_RUN_HOOK_INVOCATION,
+	BUNDLE_INVOCATION,
+]
+// Before joshuafolkken/kit#1930 nothing was rebased: a consumer received these six as the whole hook
+// command. A plain `pnpm josh <command>` is also how a project writes a hook of its own, so only the
+// exact commands count — and kit still delivers each of them through the launcher, so one left in
+// place would run its guard or formatter a second time. The list is history and never grows.
+const PLAIN_KIT_COMMANDS: ReadonlySet<string> = new Set(
+	[
+		'audit:provision',
+		'batch:guard',
+		'format:edited',
+		'investigation:guard',
+		'rule:guard',
+		'session:lang',
+	].map((command) => `${PNPM_JOSH_PREFIX}${command}`),
+)
 // The values below are matched inside raw JSON text, so the root prefix is taken in its escaped form.
 const PROJECT_ROOT_PREFIX = JSON.stringify(hook_launch.PROJECT_ROOT_PREFIX).slice(1, -1)
 // Capture the value of every `"command"` field, escapes and all, so the rewrites below touch command
@@ -80,8 +104,15 @@ function apply_hook_command_rewrite_for_destination(
 	return content
 }
 
+function is_kit_hook_command(command: string): boolean {
+	if (PLAIN_KIT_COMMANDS.has(command)) return true
+
+	return KIT_COMMAND_MARKERS.some((marker) => command.includes(marker))
+}
+
 const hook_command_rewrite = {
 	apply_hook_command_rewrite_for_destination,
+	is_kit_hook_command,
 	rewrite_hook_commands,
 }
 

package/scripts/init/init-actions.ts

@@ -106,7 +106,7 @@ function build_basic_settings_action(): FileAction {
 }
 
 function build_basic_vscode_actions(shape: ProjectShape): ReadonlyArray<FileAction> {
-	const recommendations = shape.has_web
+	const recommendations = shape.should_use_prettier
 		? [...BASIC_EXTENSIONS, PRETTIER_EXTENSION]
 		: BASIC_EXTENSIONS
 	const actions: Array<FileAction> = [
@@ -117,7 +117,7 @@ function build_basic_vscode_actions(shape: ProjectShape): ReadonlyArray<FileActi
 		),
 	]
 
-	if (shape.has_web) actions.push(build_basic_settings_action())
+	if (shape.should_use_prettier) actions.push(build_basic_settings_action())
 
 	return actions
 }
@@ -210,7 +210,7 @@ function build_basic_actions(shape: ProjectShape): ReadonlyArray<FileAction> {
 	if (shape.has_git) actions.push(build_gitignore_action())
 	if (shape.has_typescript) actions.push(build_basic_tsconfig_action())
 
-	if (shape.has_web) {
+	if (shape.should_use_prettier) {
 		actions.push({
 			dest: BASIC_PRETTIER_CONFIG,
 			create: () =>
@@ -221,6 +221,9 @@ function build_basic_actions(shape: ProjectShape): ReadonlyArray<FileAction> {
 	}
 
 	actions.push(...build_basic_vscode_actions(shape))
+	// The `.claude/settings.json` a `josh start` project receives wires the `session:lang` hook, whose
+	// unset default is `ja`, so the language is seeded from the locale as on `full`.
+	if (shape.has_workflow) actions.push(...session_language_environment.build_session_lang_actions())
 
 	return actions
 }
@@ -248,4 +251,4 @@ function build_file_actions(shape?: ProjectShape): ReadonlyArray<FileAction> {
 const init_actions = { build_file_actions, read_package_json }
 
 export type { FileAction }
-export { init_actions, PRETTIER_CONFIG_JS, BASIC_PRETTIER_CONFIG }
+export { init_actions, PRETTIER_CONFIG_JS, BASIC_PRETTIER_CONFIG, LEFTHOOK_PATH }

package/scripts/init/init-ai-copy.ts

@@ -25,9 +25,11 @@ const PRETTIER_IGNORE = '.prettierignore'
 const GIT_ATTRIBUTES = '.gitattributes'
 const CODE_OF_CONDUCT = 'CODE_OF_CONDUCT.md'
 const { SECURITY_MD } = security_policy
+const AGENTS_MD = 'AGENTS.md'
+const GEMINI_MD = 'GEMINI.md'
 const BASIC_AI_FILES = [
-	'AGENTS.md',
-	'GEMINI.md',
+	AGENTS_MD,
+	GEMINI_MD,
 	PRETTIER_IGNORE,
 	GIT_ATTRIBUTES,
 	CODE_OF_CONDUCT,
@@ -36,6 +38,8 @@ const BASIC_AI_FILES = [
 ]
 // A basic project gets its own template for these, not kit's development copy.
 const BASIC_SOURCES: Readonly<Record<string, string>> = {
+	[AGENTS_MD]: 'templates/AGENTS.basic.md',
+	[GEMINI_MD]: 'templates/GEMINI.basic.md',
 	[PRETTIER_IGNORE]: 'templates/prettierignore.basic',
 	[WORKSPACE_YAML]: 'templates/pnpm-workspace.basic.yaml',
 }
@@ -43,6 +47,9 @@ const BASIC_SOURCES: Readonly<Record<string, string>> = {
 const CONSUMER_SOURCES: Readonly<Record<string, string>> = {
 	[SECURITY_MD]: security_policy.SECURITY_TEMPLATE,
 }
+// A basic project `josh start` set up for the GitHub Issue workflow runs its agents unattended, on the
+// permissions, hooks and plugin this file declares (#3796).
+const BASIC_WORKFLOW_AI_FILES = [...BASIC_AI_FILES, '.claude/settings.json']
 const GITHUB_FILES = new Set([CODE_OF_CONDUCT, SECURITY_MD])
 const BASIC_POINTER_MAPPING = { src: 'templates/cursorrules.basic', dest: '.cursorrules' }
 const PULL_REQUEST_TEMPLATE = '.github/pull_request_template.md'
@@ -62,11 +69,15 @@ function did_read_unstamped(destination_path: string): boolean {
 	}
 }
 
-function copy_ai_file(source_path: string, destination_path: string): void {
-	const content = readFileSync(source_path, 'utf8')
+// What kit writes at a destination it copies to — the content `josh uninstall` compares a project's
+// file against, so it is read from the one place the copy itself reads it.
+function copied_content(source_path: string, destination_path: string): string {
+	return transform_copied_content(destination_path, readFileSync(source_path, 'utf8'))
+}
 
+function copy_ai_file(source_path: string, destination_path: string): void {
 	mkdirSync(path.dirname(destination_path), { recursive: true })
-	writeFileSync(destination_path, transform_copied_content(destination_path, content))
+	writeFileSync(destination_path, copied_content(source_path, destination_path))
 }
 
 // `init` declines to modify a file that already exists, and that includes not stamping it: the
@@ -132,6 +143,14 @@ function merge_existing_workspace_yaml(source_path: string, destination_path: st
 	console.info(`  ✔ updated   ${WORKSPACE_YAML}`)
 }
 
+// The workspace file kit writes where the project has none.
+function workspace_content(source_path: string, destination_path: string): string {
+	return transform_copied_content(
+		destination_path,
+		read_workspace_template(source_path, destination_path),
+	)
+}
+
 function did_skip_workspace_yaml_copy(source_path: string, destination_path: string): boolean {
 	if (existsSync(destination_path)) {
 		merge_existing_workspace_yaml(source_path, destination_path)
@@ -139,9 +158,7 @@ function did_skip_workspace_yaml_copy(source_path: string, destination_path: str
 		return false
 	}
 
-	const template = read_workspace_template(source_path, destination_path)
-
-	writeFileSync(destination_path, transform_copied_content(destination_path, template))
+	writeFileSync(destination_path, workspace_content(source_path, destination_path))
 	console.info(`  ✔ created   ${WORKSPACE_YAML}`)
 
 	return false
@@ -331,7 +348,7 @@ function should_copy_github_file(filename: string, shape?: ProjectShape): boolea
 function should_copy_basic_file(filename: string, shape?: ProjectShape): boolean {
 	if (filename !== PRETTIER_IGNORE || shape?.profile !== 'basic') return true
 
-	return shape.has_web
+	return shape.should_use_prettier
 }
 
 function should_copy_ai_file(filename: string, shape?: ProjectShape): boolean {
@@ -342,8 +359,12 @@ function should_copy_ai_file(filename: string, shape?: ProjectShape): boolean {
 	)
 }
 
+function basic_ai_files(shape: ProjectShape): ReadonlyArray<string> {
+	return shape.has_workflow ? BASIC_WORKFLOW_AI_FILES : BASIC_AI_FILES
+}
+
 function ai_files(shape?: ProjectShape): ReadonlyArray<string> {
-	const files = shape?.profile === 'basic' ? BASIC_AI_FILES : init_logic.get_ai_copy_files()
+	const files = shape?.profile === 'basic' ? basic_ai_files(shape) : init_logic.get_ai_copy_files()
 
 	return files.filter((filename) => should_copy_ai_file(filename, shape))
 }
@@ -397,6 +418,8 @@ function run_ai_copies(shape?: ProjectShape): string | undefined {
 
 const init_ai_copy = {
 	copy_ai_file,
+	copied_content,
+	workspace_content,
 	run_ai_copies,
 	ai_files,
 	ai_file_source,
@@ -405,4 +428,4 @@ const init_ai_copy = {
 	read_workspace_template,
 }
 
-export { init_ai_copy, CLAUDE_MD_FILENAME }
+export { init_ai_copy, CLAUDE_MD_FILENAME, WORKSPACE_YAML }

package/scripts/init/init-basic.ts

@@ -3,6 +3,7 @@ import { json_value } from '#scripts/lib/json-value'
 import { z } from 'zod'
 import { init_logic } from './init-logic'
 import type { ProjectShape } from './project-profile'
+import { workflow_mark } from './workflow-mark'
 
 const KIT_PACKAGE_NAME = '@joshuafolkken/kit'
 const record_schema = z.record(z.string(), z.unknown())
@@ -16,13 +17,17 @@ function initial_manifest(): string {
 	return json_format.format_json({ private: true })
 }
 
-function with_recorded_profile(content: string, profile: ProjectShape['profile']): string {
+function with_recorded_profile(
+	content: string,
+	profile: ProjectShape['profile'],
+	has_workflow = false,
+): string {
 	const parsed: unknown = JSON.parse(content)
 	const manifest = record_schema.parse(parsed)
 	const existing = manifest['josh']
 	const josh = json_value.is_record(existing) ? existing : {}
 
-	manifest['josh'] = { ...josh, profile }
+	manifest['josh'] = { ...josh, profile, ...workflow_mark.recorded_fields(has_workflow) }
 
 	return json_format.format_json(manifest)
 }
@@ -32,7 +37,7 @@ function merge_basic_manifest(
 	shape: ProjectShape,
 	versions: BasicVersions,
 ): string {
-	const with_profile = with_recorded_profile(content, shape.profile)
+	const with_profile = with_recorded_profile(content, shape.profile, shape.has_workflow)
 	const with_script = init_logic.merge_package_scripts(with_profile, {
 		preinstall: init_logic.SAFE_CHAIN_CMD,
 		josh: 'josh',
@@ -40,7 +45,7 @@ function merge_basic_manifest(
 	const with_kit = init_logic.merge_development_dependencies(with_script, {
 		[KIT_PACKAGE_NAME]: versions.kit,
 	})
-	const with_prettier = shape.has_web
+	const with_prettier = shape.should_use_prettier
 		? init_logic.merge_development_dependencies(with_kit, { prettier: versions.prettier })
 		: with_kit
 

package/scripts/init/init-bootstrap.ts

@@ -82,13 +82,17 @@ function ensure_project_manifest(project_root: string): void {
 	if (!existsSync(manifest_path)) writeFileSync(manifest_path, init_basic.initial_manifest())
 }
 
+function is_handed_off(): boolean {
+	return process.env[HANDOFF_ENV] !== undefined
+}
+
 // Returns the failure to report, or undefined once the project-installed kit finished the setup.
 function hand_off(
 	package_directory: string,
 	project_root: string,
 	args: ReadonlyArray<string>,
 ): string | undefined {
-	if (process.env[HANDOFF_ENV] !== undefined) return REPEATED_HANDOFF
+	if (is_handed_off()) return REPEATED_HANDOFF
 	console.info('\n🚀 Installing @joshuafolkken/kit into the project, then running its josh init')
 	const template = readFileSync(path.join(package_directory, KIT_BUILDS_TEMPLATE), 'utf8')
 	const install = kit_install_step(has_kit_dependency(project_root), template)
@@ -100,5 +104,5 @@ function hand_off(
 	return undefined
 }
 
-const init_bootstrap = { is_project_kit, kit_build_flags, hand_off }
+const init_bootstrap = { HANDOFF_ENV, is_project_kit, kit_build_flags, hand_off, is_handed_off }
 export { init_bootstrap }

package/scripts/init/init-dry-run-report.ts

@@ -0,0 +1,150 @@
+import { json_value } from '#scripts/lib/json-value'
+
+type ChangeKind = 'create' | 'merge' | 'overwrite' | 'delete'
+
+interface FileChange {
+	path: string
+	before: string | undefined
+	after: string | undefined
+}
+
+type JsonRecord = Record<string, unknown>
+
+const PACKAGE_JSON = 'package.json'
+const JSON_EXTENSION = '.json'
+const KIND_WIDTH = 'overwrite'.length
+const NO_CHANGES = '  (no file changes)'
+
+// Every path whose content differs between the two snapshots, sorted, so a run reads the same twice.
+function changed_files(
+	before: ReadonlyMap<string, string>,
+	after: ReadonlyMap<string, string>,
+): Array<FileChange> {
+	const paths = [...new Set([...before.keys(), ...after.keys()])].toSorted((left, right) =>
+		left.localeCompare(right),
+	)
+
+	return paths
+		.filter((file) => before.get(file) !== after.get(file))
+		.map((file) => ({ path: file, before: before.get(file), after: after.get(file) }))
+}
+
+// A changed file is a merge when every line it had survives — the project's own content is kept —
+// and an overwrite when any of its lines is replaced or removed.
+function keeps_every_line(before: string, after: string): boolean {
+	const remaining = new Set(after.split('\n'))
+
+	return before.split('\n').every((line) => remaining.has(line))
+}
+
+function is_kept_array(before: ReadonlyArray<unknown>, after: unknown): boolean {
+	if (!Array.isArray(after)) return false
+	const remaining = new Set(after.map((value) => JSON.stringify(value)))
+
+	return before.every((value) => remaining.has(JSON.stringify(value)))
+}
+
+// A JSON file is rewritten whole when kit adds to it — `package.json` written out again, a list grown — so
+// it is compared by value: a merge when every value it had is still there, wherever the lines moved.
+function is_kept(before: unknown, after: unknown): boolean {
+	if (Array.isArray(before)) return is_kept_array(before, after)
+	if (!json_value.is_record(before) || !json_value.is_record(after)) return before === after
+
+	return Object.keys(before).every((key) => is_kept(before[key], after[key]))
+}
+
+// Undefined when either side is not plain JSON (a `tsconfig.json` with comments), which falls back
+// to the line test.
+function keeps_every_value(before: string, after: string): boolean | undefined {
+	const old_value = json_value.parse_or_undefined(before)
+	const new_value = json_value.parse_or_undefined(after)
+	if (old_value === undefined || new_value === undefined) return undefined
+
+	return is_kept(old_value, new_value)
+}
+
+function keeps_content(file: string, before: string, after: string): boolean {
+	const is_kept_by_value = file.endsWith(JSON_EXTENSION)
+		? keeps_every_value(before, after)
+		: undefined
+
+	return is_kept_by_value ?? keeps_every_line(before, after)
+}
+
+function change_kind(change: FileChange): ChangeKind {
+	if (change.before === undefined) return 'create'
+	if (change.after === undefined) return 'delete'
+
+	return keeps_content(change.path, change.before, change.after) ? 'merge' : 'overwrite'
+}
+
+function parse_record(content: string | undefined): JsonRecord {
+	const parsed = content === undefined ? undefined : json_value.parse_or_undefined(content)
+
+	return json_value.is_record(parsed) ? parsed : {}
+}
+
+function changed_keys(before: JsonRecord, after: JsonRecord): Array<string> {
+	const keys = [...new Set([...Object.keys(before), ...Object.keys(after)])]
+
+	return keys.filter((key) => JSON.stringify(before[key]) !== JSON.stringify(after[key]))
+}
+
+function entry_line(name: string, before: unknown, after: unknown): string {
+	if (before === undefined) return `+ ${name} ${JSON.stringify(after)}`
+	if (after === undefined) return `- ${name}`
+
+	return `~ ${name} ${JSON.stringify(before)} → ${JSON.stringify(after)}`
+}
+
+// A missing field reads as an empty object, so a block added or removed whole is listed too.
+function as_entries(value: unknown): JsonRecord | undefined {
+	if (value === undefined) return {}
+
+	return json_value.is_record(value) ? value : undefined
+}
+
+// A field that is an object (`scripts`, `devDependencies`) is listed entry by entry, so the plan
+// names each script and dependency rather than the whole block.
+function field_lines(key: string, before: unknown, after: unknown): Array<string> {
+	const old_entries = as_entries(before)
+	const new_entries = as_entries(after)
+
+	if (old_entries === undefined || new_entries === undefined) {
+		return [entry_line(key, before, after)]
+	}
+
+	return changed_keys(old_entries, new_entries).map((name) =>
+		entry_line(`${key}.${name}`, old_entries[name], new_entries[name]),
+	)
+}
+
+function package_json_lines(change: FileChange): Array<string> {
+	const before = parse_record(change.before)
+	const after = parse_record(change.after)
+
+	return changed_keys(before, after).flatMap((key) => field_lines(key, before[key], after[key]))
+}
+
+function change_lines(change: FileChange): Array<string> {
+	const head = `  ${change_kind(change).padEnd(KIND_WIDTH)} ${change.path}`
+	if (change.path !== PACKAGE_JSON || change.after === undefined) return [head]
+
+	return [head, ...package_json_lines(change).map((line) => `      ${line}`)]
+}
+
+function format_report(
+	title: string,
+	changes: ReadonlyArray<FileChange>,
+	dependency_lines: ReadonlyArray<string>,
+): string {
+	const files =
+		changes.length === 0 ? [NO_CHANGES] : changes.flatMap((change) => change_lines(change))
+	const dependencies = dependency_lines.map((line) => `  ${line}`)
+
+	return [title, '', 'Files:', ...files, '', 'Dependencies:', ...dependencies].join('\n')
+}
+
+const init_dry_run_report = { changed_files, change_kind, package_json_lines, format_report }
+export { init_dry_run_report }
+export type { ChangeKind, FileChange }