@joshuafolkken/kit 1.978.0 → 1.998.0

package/scripts/git/git-branch.ts

@@ -84,6 +84,18 @@ function has_same_issue_prefix(branch_a: string, branch_b: string): boolean {
 	return prefix_a !== undefined && prefix_a === prefix_b
 }
 
+// The one rule `check_and_create_branch` refuses on, kept pure so `git-preflight.ts` asks it before
+// anything is pulled, switched or staged.
+function is_mismatch(
+	current_branch: string,
+	target_branch_name: string,
+	default_branch: string,
+): boolean {
+	if (current_branch === default_branch || current_branch === target_branch_name) return false
+
+	return !has_same_issue_prefix(current_branch, target_branch_name)
+}
+
 async function handle_default_branch(target_branch_name: string): Promise<void> {
 	await pull_latest()
 	const is_branch_exists: boolean = await exists(target_branch_name)
@@ -103,9 +115,7 @@ async function check_and_create_branch(
 		return target_branch_name
 	}
 
-	if (current_branch !== target_branch_name) {
-		if (has_same_issue_prefix(current_branch, target_branch_name)) return current_branch
-
+	if (is_mismatch(current_branch, target_branch_name, default_branch)) {
 		git_error.display_branch_mismatch_error(current_branch, target_branch_name)
 	}
 
@@ -118,6 +128,7 @@ const git_branch = {
 	switch_to,
 	exists,
 	check_and_create_branch,
+	is_mismatch,
 	// Exported so a lane's branch name can be checked against the real matcher rather than against a
 	// second copy of the pattern (joshuafolkken/kit#1497). A copy is what let `lane/<N>` ship: nothing
 	// asserted that the name `lane:open` writes is one this function accepts.

package/scripts/git/git-issue.ts

@@ -92,14 +92,18 @@ async function lane_issue_title(branch_name: string, issue_number: string): Prom
 	return title
 }
 
+function branch_derivation_error(branch_name: string): string {
+	return `Cannot derive issue info from branch "${branch_name}" in non-interactive mode. ${argument_hint(EXAMPLE_ISSUE_NUMBER)}`
+}
+
+function branch_number(branch_name: string): string | undefined {
+	return BRANCH_NUMBER_PATTERN.exec(branch_name)?.[1]
+}
+
 async function derive_issue_input_from_branch(branch_name: string): Promise<string> {
 	const match = BRANCH_NUMBER_PATTERN.exec(branch_name)
 
-	if (match === null) {
-		throw new Error(
-			`Cannot derive issue info from branch "${branch_name}" in non-interactive mode. ${argument_hint(EXAMPLE_ISSUE_NUMBER)}`,
-		)
-	}
+	if (match === null) throw new Error(branch_derivation_error(branch_name))
 
 	const [, number = '', slug = ''] = match
 	const title = is_lane_branch(branch_name, number)
@@ -162,6 +166,10 @@ const git_issue = {
 	get_and_display,
 	resolve_and_display,
 	derive_from_branch,
+	// The pure halves of the two resolutions above, read by `git-preflight.ts` before anything changes.
+	parse: parse_issue_input,
+	branch_number,
+	branch_derivation_error,
 }
 
 export type { IssueInfo }

package/scripts/git/git-pr.ts

@@ -202,22 +202,27 @@ async function create_for_issue(
 	)
 }
 
-async function create_with_issue_info(issue_info: IssueInfo, extra_body?: string): Promise<void> {
-	const existing_label = await existing_pr_label(issue_info.branch_name)
-
-	if (existing_label !== undefined) {
-		await create_for_issue(issue_info, extra_body, existing_label)
+// The label the pull request is opened with — also asked by `git-preflight.ts` before the commit, so
+// a missing classification is reported beside the other unmet preconditions (joshuafolkken/kit#2817).
+async function release_classification(
+	issue_number: string,
+	branch_name: string,
+): Promise<ReleaseClassification> {
+	const existing_label = await existing_pr_label(branch_name)
 
-		return
-	}
+	if (existing_label !== undefined) return existing_label
 
-	const issue_json = await git_gh_command.issue_view_json(issue_info.number, 'labels,body')
+	const issue_json = await git_gh_command.issue_view_json(issue_number, 'labels,body')
 
 	if (issue_json === undefined) {
-		throw new Error(`Could not read issue #${issue_info.number} for release classification`)
+		throw new Error(`Could not read issue #${issue_number} for release classification`)
 	}
 
-	const label = pr_classification.select_issue_classification(issue_json)
+	return pr_classification.select_issue_classification(issue_json)
+}
+
+async function create_with_issue_info(issue_info: IssueInfo, extra_body?: string): Promise<void> {
+	const label = await release_classification(issue_info.number, issue_info.branch_name)
 
 	await create_for_issue(issue_info, extra_body, label)
 }
@@ -225,6 +230,7 @@ async function create_with_issue_info(issue_info: IssueInfo, extra_body?: string
 const git_pr = {
 	create,
 	create_with_issue_info,
+	release_classification,
 }
 
 export { git_pr }

package/scripts/git/git-preflight.ts

@@ -0,0 +1,138 @@
+import { live_evidence } from '#scripts/review/live-evidence'
+import { changed_paths } from './changed-paths'
+import { git_branch } from './git-branch'
+import { git_command } from './git-command'
+import { git_gh_command } from './git-gh-command'
+import { git_issue, type IssueInfo } from './git-issue'
+import { git_pr } from './git-pr'
+
+// joshuafolkken/kit#2817. A first `josh git -y` was refused once per unmet precondition — the title's
+// issue number, the branch name, the issue's release classification — each only after the stage
+// before it had already staged, switched or pushed. **Every precondition decidable at the start is
+// asked here, before anything changes, and all of them are reported at once.** No rule is new: each
+// answer comes from the function the later stage refuses with, so the two cannot drift apart.
+
+interface PreflightInput {
+	cli_input: string | undefined
+	will_open_pr: boolean
+}
+
+// The issue the run resolves to and the branch it will commit on, when both are known.
+interface Target {
+	number: string
+	branch_name: string
+}
+
+interface Resolution {
+	target: Target | undefined
+	problems: Array<string>
+}
+
+function error_message(error: unknown): string {
+	return error instanceof Error ? error.message : String(error)
+}
+
+function resolve_from_branch(current_branch: string): Resolution {
+	const number = git_issue.branch_number(current_branch)
+
+	if (number === undefined) {
+		return { target: undefined, problems: [git_issue.branch_derivation_error(current_branch)] }
+	}
+
+	return { target: { number, branch_name: current_branch }, problems: [] }
+}
+
+// A branch is created only from the default branch, so on any other the run commits where it stands.
+function resolve_parsed(
+	parsed: IssueInfo,
+	current_branch: string,
+	default_branch: string,
+): Resolution {
+	const branch_name = current_branch === default_branch ? parsed.branch_name : current_branch
+	const target = { number: parsed.number, branch_name }
+
+	if (!git_branch.is_mismatch(current_branch, parsed.branch_name, default_branch)) {
+		return { target, problems: [] }
+	}
+
+	return {
+		target,
+		problems: [
+			`Branch mismatch: on "${current_branch}", but the title resolves to "${parsed.branch_name}".`,
+		],
+	}
+}
+
+function resolve_from_title(
+	cli_input: string,
+	current_branch: string,
+	default_branch: string,
+): Resolution {
+	try {
+		return resolve_parsed(git_issue.parse(cli_input), current_branch, default_branch)
+	} catch (error) {
+		return { target: undefined, problems: [error_message(error)] }
+	}
+}
+
+async function resolve_target(cli_input: string | undefined): Promise<Resolution> {
+	const current_branch = await git_branch.current()
+
+	if (cli_input === undefined) return resolve_from_branch(current_branch)
+
+	return resolve_from_title(cli_input, current_branch, await git_command.get_default_branch())
+}
+
+async function classification_problems(target: Target): Promise<Array<string>> {
+	try {
+		await git_pr.release_classification(target.number, target.branch_name)
+
+		return []
+	} catch (error) {
+		return [error_message(error)]
+	}
+}
+
+// A notice rather than a refusal: the evidence is the output of running the change, which does not
+// exist before the commit. Saying so now is what spares the round trip at `josh followup`.
+async function announce_evidence(branch_name: string): Promise<void> {
+	// Before staging, a new file is still untracked, so the tracked diff alone would miss it.
+	const [paths, body] = await Promise.all([
+		changed_paths.read_changed_paths(false),
+		git_gh_command.pr_get_body(branch_name),
+	])
+
+	if (live_evidence.verdict_for(paths, body) !== 'required') return
+
+	console.info(
+		`💡 This change touches runtime code: the PR body needs a ${live_evidence.EVIDENCE_HEADING} section before \`josh followup\` merges it.`,
+	)
+}
+
+function refusal(problems: ReadonlyArray<string>): Error {
+	const lines = problems.map((problem) => `  - ${problem}`)
+
+	return new Error(
+		[
+			`Preflight found ${String(problems.length)} unmet precondition(s); nothing was changed:`,
+			...lines,
+		].join('\n'),
+	)
+}
+
+async function check(input: PreflightInput): Promise<void> {
+	const { target, problems } = await resolve_target(input.cli_input)
+	// The classification and the evidence belong to the pull request, so a `--skip-pr` run asks neither.
+	const pr_target = input.will_open_pr ? target : undefined
+	const pr_problems = pr_target === undefined ? [] : await classification_problems(pr_target)
+	const all_problems = [...problems, ...pr_problems]
+
+	if (all_problems.length > 0) throw refusal(all_problems)
+
+	if (pr_target !== undefined) await announce_evidence(pr_target.branch_name)
+}
+
+const git_preflight = { check }
+
+export type { PreflightInput }
+export { git_preflight }

package/scripts/git/telegram-notify.ts

@@ -61,6 +61,8 @@ const TASK_DEFINITIONS: Record<TelegramTaskType, TaskDefinition> = {
 	stranded: { icon: '🚨', label: 'Run stranded — nobody is driving it' },
 }
 
+const NOTIFY_SWITCH_KEY = 'JOSH_NOTIFY'
+const NOTIFY_OFF_VALUE = 'off'
 const NOT_CONFIGURED_PREFIX = 'Telegram is not configured'
 const SEND_FAILED_PREFIX = 'Telegram notification failed'
 const REDACTED = '<redacted>'
@@ -136,6 +138,14 @@ function load_config(): TelegramConfig {
 	return { bot_token: result.data.telegram_bot_token, chat_id: result.data.telegram_chat_id }
 }
 
+// **An explicit opt-out is not a missing credential** (joshuafolkken/kit#2821). A consumer who never
+// meant to use Telegram had no way to say so, so every stop printed the #1564 failure as noise. Only
+// the stated value `off` disables the send: an unset or mistyped switch still falls through to
+// `load_config`, so a forgotten setup stays the loud failure #1564 made it.
+function is_notify_disabled(): boolean {
+	return parse_environment_string(process.env[NOTIFY_SWITCH_KEY]).toLowerCase() === NOTIFY_OFF_VALUE
+}
+
 function build_header(task_type: TelegramTaskType, repo_name: string | undefined): string {
 	const { icon, label } = TASK_DEFINITIONS[task_type]
 	if (repo_name === undefined || repo_name.length === 0) return `${icon} ${label}`
@@ -210,7 +220,18 @@ function build_send_failure(error: unknown, config: TelegramConfig): Error {
 // warning and exiting 0, so a message that reached nobody looked exactly like one that arrived.
 //
 // The failure it throws carries a `cause`, and that cause is redacted too — see `build_send_failure`.
+//
+// The opt-out is checked here, before `load_config`, so every caller — the tolerant form included —
+// skips the same way and none has to repeat the check.
 async function send(input: TelegramSendInput): Promise<void> {
+	if (is_notify_disabled()) {
+		console.info(
+			`🔕 Telegram notifications are disabled (${NOTIFY_SWITCH_KEY}=${NOTIFY_OFF_VALUE}).`,
+		)
+
+		return
+	}
+
 	const config = load_config()
 	const text = build_text(input)
 

package/scripts/hooks/stop-guard.ts

@@ -10,6 +10,7 @@ import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { filing_cap } from '#scripts/rules/filing-cap'
 import { lane_background } from '#scripts/rules/lane-background'
 import { lane_park } from '#scripts/rules/lane-park'
+import { last_prompt } from '#scripts/rules/last-prompt'
 import { stop_rules, type StopContext, type StopOutcome } from '#scripts/rules/stop-rules'
 import { run_cut } from '#scripts/run/run-cut'
 import { run_headless } from '#scripts/run/run-headless'
@@ -70,6 +71,7 @@ async function build_context(
 		tree_clean: !(await run_hold.is_tree_dirty()),
 		notified: lane_park.mentions_confirmation_notify(tail),
 		message: payload_tail.message,
+		prompt: last_prompt.prompt_text(tail),
 		stop_hook_active: payload_tail.stop_hook_active,
 		cut_pending: run_cut.carried_cut_sync() !== undefined,
 		filed: was_filed(tail),

package/scripts/init/basic-path-migration.ts

@@ -0,0 +1,24 @@
+// The two references `josh init` writes into a basic project, under the paths they had before
+// joshuafolkken/kit#2829 renamed the static profile. kit still ships both old paths so an earlier
+// project keeps working; re-running `josh init` moves the project onto the new ones, which is what
+// lets the old paths be retired once projects have moved.
+const RENAMED_REFERENCES: ReadonlyArray<readonly [RegExp, string]> = [
+	[
+		/@node_modules\/@joshuafolkken\/kit\/dist\/CLAUDE\.static\.md(?![\w.])/gu,
+		'@node_modules/@joshuafolkken/kit/dist/CLAUDE.basic.md',
+	],
+	[/@joshuafolkken\/kit\/prettier\/static(?=['"])/gu, '@joshuafolkken/kit/prettier/basic'],
+]
+
+function migrate_basic_paths(content: string): string {
+	let migrated = content
+
+	for (const [pattern, replacement] of RENAMED_REFERENCES) {
+		migrated = migrated.replaceAll(pattern, () => replacement)
+	}
+
+	return migrated
+}
+
+const basic_path_migration = { migrate_basic_paths }
+export { basic_path_migration }

package/scripts/init/distributed-paths.ts

@@ -97,10 +97,32 @@ function ensure_claude_md_import(existing: string | undefined): string {
 	return `${CLAUDE_MD_BOOTSTRAP}\n\n${CLAUDE_MD_IMPORT_LINE}\n\n${updated}`
 }
 
+// The lines `ensure_claude_md_import` writes. A basic project imports other rules, so a sync from
+// before joshuafolkken/kit#2827, or a switch from full, leaves these behind for it to remove.
+const FULL_CLAUDE_MD_LINES = new Set([
+	CLAUDE_MD_BOOTSTRAP,
+	OLD_CLAUDE_MD_BOOTSTRAP,
+	CLAUDE_MD_IMPORT_LINE,
+])
+
+// Each written line goes with the blank line after it, so the rest of the file is left as it was.
+function remove_claude_md_import(content: string): string {
+	const lines = content.split('\n')
+
+	return lines
+		.filter((line, index) => {
+			if (FULL_CLAUDE_MD_LINES.has(line)) return false
+
+			return line !== '' || !FULL_CLAUDE_MD_LINES.has(lines[index - 1] ?? '')
+		})
+		.join('\n')
+}
+
 const distributed_paths = {
 	transform_prompt_paths,
 	transform_distributed_paths,
 	ensure_claude_md_import,
+	remove_claude_md_import,
 	CLAUDE_MD_IMPORT_LINE,
 }
 

package/scripts/init/init-actions.ts

@@ -2,12 +2,14 @@ import { readFileSync } from 'node:fs'
 import path from 'node:path'
 import { json_format } from '#scripts/config-merge/json-format'
 import { string_array_schema, vscode_settings_schema } from '#scripts/lib/schemas'
+import { basic_path_migration } from './basic-path-migration'
 import { init_logic } from './init-logic'
 import { package_path, PROJECT_ROOT } from './init-paths'
 import type { ProjectShape } from './project-profile'
+import { session_language_environment } from './session-language-environment'
 
 const PRETTIER_CONFIG_JS = 'prettier.config.js'
-const STATIC_PRETTIER_CONFIG = 'prettier.config.mjs'
+const BASIC_PRETTIER_CONFIG = 'prettier.config.mjs'
 const VSCODE_EXTENSIONS_PATH = '.vscode/extensions.json'
 const VSCODE_SETTINGS_PATH = '.vscode/settings.json'
 const TSCONFIG_PATH = 'tsconfig.json'
@@ -17,6 +19,9 @@ interface FileAction {
 	dest: string
 	create: () => string
 	merge?: (existing: string) => string
+	// A merge that only migrates a kit-written line, for a file kit otherwise leaves to the project:
+	// when it changes nothing, the file is reported with the sample to add, as one with no merge is.
+	should_show_sample_when_unchanged?: boolean
 }
 
 function read_package_file(relative_path: string): string {
@@ -59,7 +64,7 @@ function build_vscode_actions(): ReadonlyArray<FileAction> {
 	]
 }
 
-const STATIC_EXTENSIONS = [
+const BASIC_EXTENSIONS = [
 	'streetsidesoftware.code-spell-checker',
 	'pkief.material-icon-theme',
 	'usernamehw.errorlens',
@@ -69,16 +74,16 @@ const STATIC_EXTENSIONS = [
 const PRETTIER_EXTENSION = 'esbenp.prettier-vscode'
 const DEFAULT_FORMATTER = 'editor.defaultFormatter'
 const FORMAT_ON_SAVE = 'editor.formatOnSave'
-const STATIC_LANGUAGES = ['[html]', '[css]', '[javascript]']
+const BASIC_LANGUAGES = ['[html]', '[css]', '[javascript]']
 
-function static_settings(): Record<string, Record<string, unknown>> {
+function basic_settings(): Record<string, Record<string, unknown>> {
 	const formatter = { [DEFAULT_FORMATTER]: PRETTIER_EXTENSION, [FORMAT_ON_SAVE]: true }
 
-	return Object.fromEntries(STATIC_LANGUAGES.map((language) => [language, formatter]))
+	return Object.fromEntries(BASIC_LANGUAGES.map((language) => [language, formatter]))
 }
 
-function build_static_settings_action(): FileAction {
-	const settings = static_settings()
+function build_basic_settings_action(): FileAction {
+	const settings = basic_settings()
 
 	return build_action(
 		VSCODE_SETTINGS_PATH,
@@ -87,10 +92,10 @@ function build_static_settings_action(): FileAction {
 	)
 }
 
-function build_static_vscode_actions(shape: ProjectShape): ReadonlyArray<FileAction> {
+function build_basic_vscode_actions(shape: ProjectShape): ReadonlyArray<FileAction> {
 	const recommendations = shape.has_web
-		? [...STATIC_EXTENSIONS, PRETTIER_EXTENSION]
-		: STATIC_EXTENSIONS
+		? [...BASIC_EXTENSIONS, PRETTIER_EXTENSION]
+		: BASIC_EXTENSIONS
 	const actions: Array<FileAction> = [
 		build_action(
 			VSCODE_EXTENSIONS_PATH,
@@ -99,12 +104,12 @@ function build_static_vscode_actions(shape: ProjectShape): ReadonlyArray<FileAct
 		),
 	]
 
-	if (shape.has_web) actions.push(build_static_settings_action())
+	if (shape.has_web) actions.push(build_basic_settings_action())
 
 	return actions
 }
 
-function build_static_tsconfig_action(): FileAction {
+function build_basic_tsconfig_action(): FileAction {
 	return build_action(
 		TSCONFIG_PATH,
 		() => json_format.format_json({ extends: init_logic.get_tsconfig_extends_entry() }),
@@ -187,26 +192,28 @@ function build_gitignore_action(): FileAction {
 	)
 }
 
-function build_static_actions(shape: ProjectShape): ReadonlyArray<FileAction> {
+function build_basic_actions(shape: ProjectShape): ReadonlyArray<FileAction> {
 	const actions: Array<FileAction> = []
 	if (shape.has_git) actions.push(build_gitignore_action())
-	if (shape.has_typescript) actions.push(build_static_tsconfig_action())
+	if (shape.has_typescript) actions.push(build_basic_tsconfig_action())
 
 	if (shape.has_web) {
 		actions.push({
-			dest: STATIC_PRETTIER_CONFIG,
+			dest: BASIC_PRETTIER_CONFIG,
 			create: () =>
-				"import { config } from '@joshuafolkken/kit/prettier/static'\n\nexport default config\n",
+				"import { config } from '@joshuafolkken/kit/prettier/basic'\n\nexport default config\n",
+			merge: (existing) => basic_path_migration.migrate_basic_paths(existing),
+			should_show_sample_when_unchanged: true,
 		})
 	}
 
-	actions.push(...build_static_vscode_actions(shape))
+	actions.push(...build_basic_vscode_actions(shape))
 
 	return actions
 }
 
 function build_file_actions(shape?: ProjectShape): ReadonlyArray<FileAction> {
-	if (shape?.profile === 'static') return build_static_actions(shape)
+	if (shape?.profile === 'basic') return build_basic_actions(shape)
 
 	return [
 		...(shape?.has_git === false ? [] : [build_gitignore_action()]),
@@ -226,10 +233,11 @@ function build_file_actions(shape?: ProjectShape): ReadonlyArray<FileAction> {
 		...build_config_file_actions().filter(
 			(action) => shape?.has_git !== false || action.dest !== LEFTHOOK_PATH,
 		),
+		...session_language_environment.build_session_lang_actions(),
 	]
 }
 
 const init_actions = { build_file_actions, read_package_json }
 
 export type { FileAction }
-export { init_actions, PRETTIER_CONFIG_JS }
+export { init_actions, PRETTIER_CONFIG_JS, BASIC_PRETTIER_CONFIG }