@joshuafolkken/kit 1.983.0 → 1.1003.0

package/scripts/run/run-preflight.ts

@@ -1,5 +1,6 @@
 import { git_command } from '#scripts/git/git-command'
 import { git_gh_pr_read } from '#scripts/git/git-gh-pr-read'
+import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 import { z } from 'zod'
 import { run_hold } from './run-hold'
 import { run_issue_number } from './run-issue-number'
@@ -72,7 +73,7 @@ const GH_PR_STATES: ReadonlyMap<string, PrState> = new Map([
 ])
 
 const CLEAN_REASON =
-	'Nothing was left behind: the tree is clean, HEAD is on the default branch, and this issue has no branch or pull request.'
+	'Nothing was left behind: the tree is clean, HEAD is on the default branch, and this issue has no pull request and no branch holding work.'
 
 const CLEAN_ADVICE = 'Start the child.'
 
@@ -283,22 +284,91 @@ function to_head_branch(name: string): string {
 	return separator_index === NOT_FOUND_INDEX ? name : name.slice(separator_index + 1)
 }
 
-async function read_branch_candidates(issue: string): Promise<Array<string>> {
+function group_by_head(pairs: ReadonlyArray<[string, string]>): Map<string, Array<string>> {
+	const groups = new Map<string, Array<string>>()
+
+	for (const [name, reference] of pairs) groups.set(name, [...(groups.get(name) ?? []), reference])
+
+	return groups
+}
+
+// Each candidate keeps every ref it was found as — the local branch and each remote-tracking ref —
+// because either may be the one holding the commits: a local branch left at the default branch can
+// sit beside a remote one another machine pushed work to, and the stripped head name may not resolve.
+async function read_branch_candidates(issue: string): Promise<Map<string, Array<string>>> {
 	const pattern = `${issue}${ISSUE_BRANCH_SUFFIX}`
 	const [local, remote] = await Promise.all([
 		git_command.branch_names(pattern),
 		git_command.branch_names_remote(`${ANY_REMOTE_PREFIX}${pattern}`),
 	])
 
-	return [...new Set([...local, ...remote.map((name) => to_head_branch(name))])]
+	return group_by_head([
+		...local.map((name): [string, string] => [name, name]),
+		...remote.map((reference): [string, string] => [to_head_branch(reference), reference]),
+	])
+}
+
+async function has_commits_beyond(
+	base: string,
+	references: ReadonlyArray<string>,
+): Promise<boolean> {
+	const counts = await Promise.all(
+		references.map(async (reference) => await git_command.commit_count_beyond(base, reference)),
+	)
+
+	return counts.some((count) => count > 0)
+}
+
+// **A lane stopped mid-implementation holds its work uncommitted**, on a branch with no commit yet —
+// so the lane checked out on the candidate is asked whether its tree is dirty, read the way
+// `run_hold` reads this tree (an unreadable status is dirty). A lane on another branch, or whose
+// directory is gone, holds nothing for this candidate.
+async function is_held_dirty(name: string, lane: LaneInfo | undefined): Promise<boolean> {
+	if (lane?.branch !== name || lane.is_stranded) return false
+
+	return await run_hold.is_tree_dirty(lane.directory)
+}
+
+interface CandidateContext {
+	base: string
+	lane: LaneInfo | undefined
+}
+
+// **A branch with no pull request, no commit beyond the default branch and no uncommitted change in
+// its lane holds no work** (joshuafolkken/kit#2855). A lane that ended before implementing — an
+// operational issue with no code change — leaves exactly that behind, and reading its mere existence
+// as a partial implementation sent the next `fullrun #N` to `resume` over nothing. A branch with a
+// pull request is never counted: whatever its commits, the pull request is the state the verdict is
+// decided on.
+async function read_candidate(
+	name: string,
+	references: ReadonlyArray<string>,
+	context: CandidateContext,
+): Promise<ChildState | undefined> {
+	const state = await read_pr_of_branch(name)
+
+	if (state.pr_state !== NO_PR) return state
+	if (await has_commits_beyond(context.base, references)) return state
+
+	return (await is_held_dirty(name, context.lane)) ? state : undefined
 }
 
 async function read_child_state(issue: string): Promise<ChildState> {
 	const candidates = await read_branch_candidates(issue)
 
-	return pick_child_state(
-		await Promise.all(candidates.map(async (name) => await read_pr_of_branch(name))),
+	if (candidates.size === 0) return NO_CHILD_WORK
+
+	const [base, lane] = await Promise.all([
+		git_command.default_branch_reference(),
+		lane_registry.find_open_lane(issue),
+	])
+	const reads = await Promise.all(
+		[...candidates].map(
+			async ([name, references]) => await read_candidate(name, references, { base, lane }),
+		),
 	)
+
+	return pick_child_state(reads.filter((read): read is ChildState => read !== undefined))
 }
 
 // The child read is skipped where the tree already answers `reclaim`: a `gh` round trip buys nothing

package/scripts/run/run-progress-cli.ts

@@ -77,7 +77,12 @@ const WAIT_EXPIRED_NOTICE = `The watch bound (\`--hours\`, ${String(DEFAULT_MAX_
 // The repository name is only ever printed, never written against, so the bounded lookup is the right
 // one: a `gh` call that hangs would otherwise block the synchronous read at startup and leave the
 // watcher neither running nor saying so.
-const REPO_LOOKUP_TIMEOUT_MS = 10_000
+const REPO_LOOKUP_TIMEOUT_SECONDS = 10
+const REPO_LOOKUP_TIMEOUT_MS = REPO_LOOKUP_TIMEOUT_SECONDS * run_progress.MS_PER_SECOND
+// A lookup that timed out or failed is not an argument the caller got wrong, so it is told apart from
+// the usage error — read as one, it sent a person to fix arguments that were correct
+// (joshuafolkken/kit#2859).
+const REPO_UNRESOLVED_NOTICE = `The repository could not be resolved (\`gh\` did not answer within ${String(REPO_LOOKUP_TIMEOUT_SECONDS)}s or failed), so the progress watcher did not start. Pass \`--repo <owner/repo>\` and start it again.`
 
 const DECLINE_NOTICES: Readonly<Record<'idle' | 'unreadable', string>> = {
 	idle: IDLE_NOTICE,
@@ -141,6 +146,12 @@ function report_usage(): number {
 	return FAILURE_EXIT_CODE
 }
 
+function report_repo_unresolved(): number {
+	console.error(REPO_UNRESOLVED_NOTICE)
+
+	return FAILURE_EXIT_CODE
+}
+
 function report_disabled(): number {
 	console.error(DISABLED_NOTICE)
 
@@ -443,7 +454,7 @@ function to_options(values: ParsedValues): WatchOptions | undefined {
 async function run_watch(values: ParsedValues): Promise<number> {
 	const options = to_options(values)
 
-	if (options === undefined) return report_usage()
+	if (options === undefined) return report_repo_unresolved()
 	if (values.once === true) return await once(options)
 	if (values.wait === true) return await wait_once(options)
 
@@ -487,6 +498,7 @@ const run_progress_cli = {
 	IDLE_NOTICE,
 	LANE_CHILD_NOTICE,
 	MARKED_NOTICE,
+	REPO_UNRESOLVED_NOTICE,
 	TICK_SECONDS,
 	UNREADABLE_NOTICE,
 	USAGE,

package/scripts/safe-chain/ci-installer-pin.ts

@@ -1,16 +1,14 @@
 import { createHash } from 'node:crypto'
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { execaSync } from 'execa'
 
-// The workflows that install safe-chain on the runner. Each carries the release and the installer's
-// SHA-256 as workflow-level env, so one pin per file moves every "Setup safe-chain" step at once
-// (joshuafolkken/kit#2711, joshuafolkken/kit#2765). A consumer has the first and the last, and
-// `josh sync` rewrites both from kit, so moving them anywhere but kit is harmless and short-lived.
-const WORKFLOW_PATHS = [
-	'.github/workflows/ci.yml',
-	'templates/workflows/ci.yml',
-	'.github/workflows/pr-classification.yml',
-]
+// Where the workflows that install safe-chain on the runner live. Each carries the release and the
+// installer's SHA-256 as workflow-level env, so one pin per file moves every "Setup safe-chain" step
+// at once (joshuafolkken/kit#2711, joshuafolkken/kit#2765). The directories are scanned rather than
+// a file list kept, so a workflow another package distributes — app-kit's `dast.yml` and `load.yml`
+// — moves with the rest (joshuafolkken/kit#2830); a file without the pin is never a target.
+const WORKFLOW_DIRECTORIES = ['.github/workflows', 'templates/workflows']
+const WORKFLOW_FILE_RE = /\.ya?ml$/u
 // `[ \t]` rather than `\s`: under the `m` flag `\s*` would run across line ends and swallow the
 // blank line that follows the env block.
 const VERSION_RE = /^(?<key>[ \t]*SAFE_CHAIN_INSTALLER_VERSION:[ \t]*)(?<value>\S+)[ \t]*$/mu
@@ -27,6 +25,15 @@ function installer_url(version: string): string {
 	return `https://github.com/AikidoSec/safe-chain/releases/download/${version}/install-safe-chain.sh`
 }
 
+function list_workflows(): Array<string> {
+	return WORKFLOW_DIRECTORIES.filter((directory) => existsSync(directory)).flatMap((directory) =>
+		readdirSync(directory)
+			.filter((file_name) => WORKFLOW_FILE_RE.test(file_name))
+			.toSorted((left, right) => left.localeCompare(right))
+			.map((file_name) => `${directory}/${file_name}`),
+	)
+}
+
 function extract_pinned_version(content: string): string | undefined {
 	return VERSION_RE.exec(content)?.groups?.[VALUE_GROUP]
 }
@@ -66,7 +73,7 @@ function write_pin(workflow_path: string, pin: InstallerPin): void {
 	writeFileSync(workflow_path, rewrite_pin(readFileSync(workflow_path, 'utf8'), pin), 'utf8')
 }
 
-function sync(latest: string, workflow_paths: ReadonlyArray<string> = WORKFLOW_PATHS): void {
+function sync(latest: string, workflow_paths: ReadonlyArray<string> = list_workflows()): void {
 	const targets = stale_workflows(latest, workflow_paths)
 	if (targets.length === 0) return
 
@@ -82,7 +89,7 @@ function sync(latest: string, workflow_paths: ReadonlyArray<string> = WORKFLOW_P
 }
 
 const ci_installer_pin = {
-	WORKFLOW_PATHS,
+	list_workflows,
 	installer_url,
 	extract_pinned_version,
 	rewrite_pin,

package/scripts/safe-chain/project-config.ts

@@ -146,4 +146,4 @@ function sync_project_config(root: string): boolean {
 
 const project_config = { merge_project_config, sync_project_config }
 
-export { project_config }
+export { project_config, PROJECT_CONFIG_FILE }

package/scripts/sync/sync-ai-files.ts

@@ -0,0 +1,204 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { init_ai_copy } from '#scripts/init/init-ai-copy'
+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 type { ProjectShape } from '#scripts/init/project-profile'
+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_hook_safety } from './sync-hook-safety'
+
+const WORKSPACE_YAML = 'pnpm-workspace.yaml'
+const PACKAGE_JSON = '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(source: string, filename: string): void {
+	if (should_skip_hook_file(filename)) return
+	const did_change = sync_ai_file(path.join(PACKAGE_DIR, source), 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)
+}
+
+// The source is the profile's: a basic project syncs from its own templates, as `josh init` wrote it.
+function sync_ai_copy_file(filename: string, is_force: boolean, shape?: ProjectShape): void {
+	const source = init_ai_copy.ai_file_source(filename, shape)
+
+	if (filename === WORKSPACE_YAML) {
+		const did_change = sync_workspace_yaml(
+			path.join(PACKAGE_DIR, source),
+			path.join(PROJECT_ROOT, WORKSPACE_YAML),
+			is_force,
+		)
+
+		console.info(`  ✔ ${did_change ? 'synced   ' : 'unchanged'} ${WORKSPACE_YAML}`)
+
+		return
+	}
+
+	sync_file(source, 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})`)
+}
+
+// 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)
+}
+
+function ensured_claude_md(existing: string | undefined, shape?: ProjectShape): string {
+	return shape?.profile === 'basic'
+		? init_ai_copy.ensure_basic_claude_md(existing)
+		: init_logic.ensure_claude_md_import(existing)
+}
+
+// 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, shape?: ProjectShape): void {
+	const existing = existsSync(destination_path) ? readFileSync(destination_path, 'utf8') : undefined
+	const ensured = ensured_claude_md(existing, shape)
+
+	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}`)
+}
+
+// A basic shape syncs the file set `josh init` writes for that profile; no shape is the full set,
+// unfiltered, as sync has always written it (joshuafolkken/kit#2827).
+function sync_ai_copy_all(is_force: boolean, shape?: ProjectShape): void {
+	console.info('AI files:')
+
+	sync_claude_md(path.join(PROJECT_ROOT, CLAUDE_MD_FILENAME), shape)
+
+	for (const filename of init_ai_copy.ai_files(shape)) {
+		sync_ai_copy_file(filename, is_force, shape)
+	}
+
+	for (const { src, dest } of init_ai_copy.ai_file_mappings(shape)) {
+		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()
+}
+
+const sync_ai_files = {
+	should_skip_hook_file,
+	sync_file_mapping,
+	sync_ai_file,
+	sync_workspace_yaml,
+	sync_claude_md,
+	sync_directory,
+	sync_ai_copy_all,
+}
+
+export { sync_ai_files }