@joshuafolkken/kit 1.947.0 → 1.957.0

package/scripts/josh/josh-commands-project.ts

@@ -14,9 +14,13 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 	},
 	start: {
 		script: 'scripts/init/start.ts',
-		description: 'Initialize a project for the GitHub Issue workflow',
+		description: 'Create a new project for the GitHub Issue workflow, from git init to labels',
 		category: 'Project',
-		reference: [PROFILE_ARGUMENTS, 'developer', ['files', 'git', 'network']],
+		reference: [
+			`${PROFILE_ARGUMENTS} [--yes] [--github] [--public]`,
+			'developer',
+			['files', 'git', 'network', 'processes'],
+		],
 	},
 	init: {
 		script: 'scripts/init/init.ts',

package/scripts/run/run-retrospective.ts

@@ -0,0 +1,34 @@
+import { hook_decision } from '#scripts/josh/hook-decision'
+
+// Whether a run owes its end-of-run retrospective, single-sourced so `run:step` and `backlog:drive`
+// never disagree on it (joshuafolkken/kit#2750): a drive that read "owed" where `run:step` read "not
+// owed" handed back at every drain to a session that had nothing to run.
+
+// The opt-in switch that gates the retrospective (joshuafolkken/kit#2370). It defaults off, so an unset
+// variable owes no retrospective.
+const RETROSPECTIVE_ENV_KEY = 'JOSH_RETROSPECTIVE'
+
+interface RetrospectiveFacts {
+	is_retrospective_enabled: boolean
+	is_lane_child: boolean
+	is_retrospective_done: boolean
+	is_consumer: boolean
+}
+
+function is_enabled(): boolean {
+	return hook_decision.is_switch_opt_in(RETROSPECTIVE_ENV_KEY)
+}
+
+// False when the switch is off, for a dispatched lane child (the batch runs one at its own end, never a
+// child's), once it has run this invocation, and in a consumer checkout, where the kit-only command is
+// refused. The switch is read first, so a run that has not opted in never consults the other three.
+function is_owed(facts: RetrospectiveFacts): boolean {
+	if (!facts.is_retrospective_enabled) return false
+
+	return !facts.is_lane_child && !facts.is_retrospective_done && !facts.is_consumer
+}
+
+const run_retrospective = { RETROSPECTIVE_ENV_KEY, is_enabled, is_owed }
+
+export type { RetrospectiveFacts }
+export { run_retrospective }

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

@@ -9,6 +9,7 @@ import { run_carry, type CarryRead } from './run-carry'
 import { run_event_scope } from './run-event-scope'
 import { run_event_stream } from './run-event-stream'
 import { run_prep_cli } from './run-prep-cli'
+import { run_retrospective } from './run-retrospective'
 import { run_step, type StepInput } from './run-step'
 
 // `josh run:step <N>` — print the run's next single action, computed from the event stream, the carry
@@ -22,10 +23,6 @@ const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
 const USAGE = 'Usage: josh run:step <issue-number>'
-// The opt-in switch that gates the end-of-run retrospective (joshuafolkken/kit#2370). Read here rather
-// than in `run-step.ts` so the position logic stays a pure function of its input; it defaults off, so an
-// unset variable prints no retrospective step.
-const RETROSPECTIVE_ENV_KEY = 'JOSH_RETROSPECTIVE'
 
 interface RunReads {
 	carry_kind: CarryRead['kind']
@@ -83,7 +80,8 @@ async function gather(issue_number: string): Promise<StepInput> {
 		is_at_cut_cap: run_reads.is_at_cut_cap,
 		is_lane_child: lane_child_marker.is_child_of(process.cwd()),
 		is_consumer: doctor_consumer.is_kit_consumer(find_package_directory(process.cwd())),
-		is_retrospective_enabled: hook_decision.is_switch_opt_in(RETROSPECTIVE_ENV_KEY),
+		// Read here rather than in `run-step.ts` so the position logic stays a pure function of its input.
+		is_retrospective_enabled: run_retrospective.is_enabled(),
 		has_changes: parts.has_changes,
 		has_completion_callback: agent_role_profile.has_completion_callback(),
 	}

package/scripts/run/run-step.ts

@@ -2,6 +2,7 @@ import { git_stash } from '#scripts/git/git-stash'
 import { latest_scope_cli } from '#scripts/version/latest-scope-cli'
 import type { CarryRead } from './run-carry'
 import { run_event_stream } from './run-event-stream'
+import { run_retrospective } from './run-retrospective'
 
 // `josh run:step <N>` — the run's next single action, computed from three mechanical inputs and nothing
 // else (joshuafolkken/kit#2248). It is the child of epic #2166 that lifts the fold from an *event* to a
@@ -174,23 +175,10 @@ const EVENT_ACTIONS: Record<string, (issue_number: string) => StepAction> = {
 // (joshuafolkken/kit#2297).
 const PARENT_ONLY_EVENTS: ReadonlySet<string> = new Set([KIND.MERGE, KIND.OUTAGE])
 
-// Whether a run at a winding-down position still owes its end-of-run retrospective
-// (joshuafolkken/kit#2328) — false when the switch is off (the opt-in default, joshuafolkken/kit#2370),
-// for a dispatched lane child, where the batch runs one at its own end and never a child's (the
-// `release:scope` precedent), for a run whose retrospective has already run this invocation, and in a
-// consumer checkout, where the kit-only command is refused. The switch is read first, so a run that has
-// not opted in never consults the other three. The two positions that consult it are the drain and the
-// stop; both read exactly this, so the exclusion set is single-sourced.
-function is_retrospective_owed(input: StepInput): boolean {
-	if (!input.is_retrospective_enabled) return false
-
-	return !input.is_lane_child && !input.is_retrospective_done && !input.is_consumer
-}
-
 // A stopped run's last owed step is the end-of-run retrospective. When it is not owed the position stops
 // with no command to run, which is what the position meant before the retrospective existed.
 function stop_action(input: StepInput): StepAction {
-	return is_retrospective_owed(input) ? command(RETROSPECTIVE_COMMAND) : verdict(STOP)
+	return run_retrospective.is_owed(input) ? command(RETROSPECTIVE_COMMAND) : verdict(STOP)
 }
 
 // The drain fires the retrospective *before* the idle watch, not after it (joshuafolkken/kit#2335): the
@@ -199,7 +187,7 @@ function stop_action(input: StepInput): StepAction {
 // run proceeds to that watch, which is a `WAIT` rather than a `STOP`: the backlog is empty but the run is
 // not ending, and the real `STOP` follows when the watch expires with the retrospective already done.
 function drain_action(input: StepInput): StepAction {
-	return is_retrospective_owed(input) ? command(RETROSPECTIVE_COMMAND) : verdict(WAIT)
+	return run_retrospective.is_owed(input) ? command(RETROSPECTIVE_COMMAND) : verdict(WAIT)
 }
 
 // The hand-off a `backlogrun` parent without a completion callback takes right after dispatching

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

@@ -1,12 +1,16 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
+import { release_age } from '#scripts/version/release-age'
 import { yaml_document } from '#scripts/yaml/yaml-document'
 import { dump } from 'js-yaml'
 import { z } from 'zod'
 
 const WORKSPACE_FILE = 'pnpm-workspace.yaml'
 const PROJECT_CONFIG_FILE = '.aikido'
+const NPMRC_FILE = '.npmrc'
 const EXCLUSIONS_FIELD = 'minimumPackageAgeExclusions'
+const AGE_FIELD = 'minimumPackageAgeHours'
+const MINUTES_PER_HOUR = 60
 const workspace_schema = z.object({ minimumReleaseAgeExclude: z.array(z.string()).optional() })
 
 function read_mapping(value: unknown, label: string): Record<string, unknown> {
@@ -72,27 +76,68 @@ function replace_safe_chain_block(existing: string, safe_chain: Record<string, u
 	return `${prefix}${prefix ? '\n' : ''}${replacement}${suffix}`
 }
 
-function merge_project_config(existing: string, workspace: string): string {
-	const source = workspace_schema.parse(yaml_document.parse_yaml(workspace))
-	const exclusions = source.minimumReleaseAgeExclude ?? []
-	const aikido = yaml_document.parse_yaml(existing)
-	const safe_chain = read_mapping(aikido['safe-chain'], 'safe-chain')
+// Safe Chain enforces its own minimum package age (48 hours by default), so CI refused lockfiles pnpm
+// had resolved under `.npmrc`'s shorter window (kit #2743). `.npmrc` is the source: its minutes are
+// floored to whole hours so Safe Chain is never stricter than pnpm, and an undeclared window writes
+// nothing; an explicit `0` opt-out is written as 0 so an earlier synchronized age cannot outlive it.
+function package_age_hours(npmrc: string): number | undefined {
+	const minutes = release_age.parse_declared_minimum_release_age(npmrc)
+	if (minutes === undefined) return undefined
+
+	return Math.floor(minutes / MINUTES_PER_HOUR)
+}
+
+function merge_age(safe_chain: Record<string, unknown>, npmrc: string): Record<string, unknown> {
+	const hours = package_age_hours(npmrc)
+	if (hours === undefined) return safe_chain
+
+	return { ...safe_chain, [AGE_FIELD]: hours }
+}
+
+function merge_exclusions(
+	safe_chain: Record<string, unknown>,
+	exclusions: ReadonlyArray<string>,
+): Record<string, unknown> {
 	const npm = read_mapping(safe_chain['npm'], 'safe-chain.npm')
-	if (JSON.stringify(npm[EXCLUSIONS_FIELD]) === JSON.stringify(exclusions)) return existing
-	if (exclusions.length === 0 && existing.length === 0) return existing
 
-	const merged = { ...safe_chain, npm: { ...npm, [EXCLUSIONS_FIELD]: exclusions } }
+	return { ...safe_chain, npm: { ...npm, [EXCLUSIONS_FIELD]: exclusions } }
+}
+
+function has_nothing_to_write(
+	existing: string,
+	exclusions: ReadonlyArray<string>,
+	npmrc: string,
+): boolean {
+	return existing.length === 0 && exclusions.length === 0 && package_age_hours(npmrc) === undefined
+}
+
+function read_exclusions(workspace: string): ReadonlyArray<string> {
+	return workspace_schema.parse(yaml_document.parse_yaml(workspace)).minimumReleaseAgeExclude ?? []
+}
+
+function merge_project_config(existing: string, workspace: string, npmrc = ''): string {
+	const exclusions = read_exclusions(workspace)
+	const aikido = yaml_document.parse_yaml(existing)
+	const safe_chain = read_mapping(aikido['safe-chain'], 'safe-chain')
+	const merged = merge_age(merge_exclusions(safe_chain, exclusions), npmrc)
+	if (JSON.stringify(merged) === JSON.stringify(safe_chain)) return existing
+	if (has_nothing_to_write(existing, exclusions, npmrc)) return existing
 
 	return replace_safe_chain_block(existing, merged)
 }
 
+function read_optional(file_path: string): string {
+	return existsSync(file_path) ? readFileSync(file_path, 'utf8') : ''
+}
+
 function sync_project_config(root: string): boolean {
 	const workspace_path = path.join(root, WORKSPACE_FILE)
 	if (!existsSync(workspace_path)) return false
 	const config_path = path.join(root, PROJECT_CONFIG_FILE)
-	const existing = existsSync(config_path) ? readFileSync(config_path, 'utf8') : ''
+	const existing = read_optional(config_path)
 	const workspace = readFileSync(workspace_path, 'utf8')
-	const merged = merge_project_config(existing, workspace)
+	const npmrc = read_optional(path.join(root, NPMRC_FILE))
+	const merged = merge_project_config(existing, workspace, npmrc)
 	if (merged === existing) return false
 	writeFileSync(config_path, merged)
 

package/scripts/sync/sync.ts

@@ -371,7 +371,6 @@ function report_repository_settings(name_with_owner: string | undefined): void {
 
 function sync_project_artifacts(is_force: boolean): void {
 	sync_ai_copy_all(is_force)
-	project_config.sync_project_config(PROJECT_ROOT)
 	sync_prettier_config(path.join(PROJECT_ROOT, 'prettier.config.js'))
 	sync_playwright_config(path.join(PROJECT_ROOT, 'playwright.config.ts'))
 	sync_deploy_vps(path.join(PROJECT_ROOT, '.github/workflows/deploy-vps.yml'))
@@ -382,6 +381,9 @@ function sync_project_artifacts(is_force: boolean): void {
 
 	sync_sonar_with_template(name_with_owner, is_force)
 	sync_config_files()
+	// After `sync_config_files`, which may add the `.npmrc` window `.aikido`'s age is derived from
+	// (joshuafolkken/kit#2743).
+	project_config.sync_project_config(PROJECT_ROOT)
 	sync_package_json_migrations(path.join(PROJECT_ROOT, PACKAGE_JSON))
 	report_repository_settings(name_with_owner)
 }

package/scripts/version/release-age.ts

@@ -19,12 +19,18 @@ const NPMRC_PATH = '.npmrc'
 const release_times_schema = z.record(z.string(), z.string())
 const MS_PER_MINUTE = 60_000
 
+// The window `.npmrc` content declares, or nothing when it does not declare one — an explicit
+// `minimum-release-age=0` stays 0 rather than collapsing into "not declared".
+function parse_declared_minimum_release_age(npmrc_content: string): number | undefined {
+	const raw = MINIMUM_RELEASE_AGE_RE.exec(npmrc_content)?.[1]
+
+	return raw === undefined ? undefined : Number(raw)
+}
+
 // The quarantine window in minutes from `.npmrc`; a missing or malformed entry means no
 // quarantine, matching pnpm's own default for the setting.
 function parse_minimum_release_age(npmrc_content: string): number {
-	const raw = MINIMUM_RELEASE_AGE_RE.exec(npmrc_content)?.[1]
-
-	return raw === undefined ? NO_QUARANTINE_MINUTES : Number(raw)
+	return parse_declared_minimum_release_age(npmrc_content) ?? NO_QUARANTINE_MINUTES
 }
 
 // Stable releases only, on the requested major, published at or before the cutoff. The
@@ -82,9 +88,7 @@ function select_aged_version(
 // `minimum-release-age=0` opt-out stop the walk instead of falling through to an ancestor's policy.
 function read_declared_minimum_release_age(npmrc_path: string): number | undefined {
 	try {
-		const raw = MINIMUM_RELEASE_AGE_RE.exec(readFileSync(npmrc_path, 'utf8'))?.[1]
-
-		return raw === undefined ? undefined : Number(raw)
+		return parse_declared_minimum_release_age(readFileSync(npmrc_path, 'utf8'))
 	} catch {
 		return undefined
 	}
@@ -138,6 +142,7 @@ function read_nearest_minimum_release_age(start: string, boundary?: string): num
 const release_age = {
 	release_times_schema,
 	parse_minimum_release_age,
+	parse_declared_minimum_release_age,
 	read_minimum_release_age,
 	read_nearest_minimum_release_age,
 	select_aged_version,