@joshuafolkken/kit 1.1455.0 → 1.1514.0

package/scripts/josh/command-usage.ts

@@ -0,0 +1,110 @@
+import { canonical_command, COMMAND_MAP } from './josh-command-map'
+import type { CommandUsage } from './josh-command-types'
+import { AUTOMATION_USAGE } from './josh-usage-automation'
+import { BACKLOG_USAGE } from './josh-usage-backlog'
+import { DEVELOPER_USAGE } from './josh-usage-developer'
+import { HOOK_USAGE } from './josh-usage-hooks'
+import { ISSUE_USAGE } from './josh-usage-issue'
+import { REVIEW_USAGE } from './josh-usage-review'
+import { RUN_USAGE } from './josh-usage-run'
+import { SESSION_USAGE } from './josh-usage-session'
+import { WORKFLOW_USAGE } from './josh-usage-workflow'
+
+// The single renderer of a command's usage. `josh help <command>` prints it and
+// `scripts/document/generate-command-usage.ts` writes it between a reference page's usage markers,
+// so the terminal and the page are one text (#3932).
+
+type UsageTable = Readonly<Record<string, CommandUsage>>
+
+// Which reference page renders each usage table — the one place a table is tied to its page, so the
+// generator's coverage check and `josh help` read the same set (#3981).
+/* eslint-disable @typescript-eslint/naming-convention */
+const USAGE_PAGE_TABLES: Readonly<Record<string, ReadonlyArray<UsageTable>>> = {
+	'docs/josh-commands.md': [DEVELOPER_USAGE],
+	'docs/josh-commands-run.md': [RUN_USAGE, SESSION_USAGE],
+	'docs/josh-commands-backlog.md': [ISSUE_USAGE, BACKLOG_USAGE, REVIEW_USAGE],
+	'docs/josh-commands-automation.md': [AUTOMATION_USAGE, WORKFLOW_USAGE, HOOK_USAGE],
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+const COMMAND_USAGE: UsageTable = Object.fromEntries(
+	Object.values(USAGE_PAGE_TABLES)
+		.flat()
+		.flatMap((table) => Object.entries(table)),
+)
+const NOTE_GAP = 3
+
+interface ExampleLine {
+	command: string
+	note: string | undefined
+}
+
+function usage_for(name: string): CommandUsage | undefined {
+	return Object.hasOwn(COMMAND_USAGE, name) ? COMMAND_USAGE[name] : undefined
+}
+
+function example_line(name: string, example: CommandUsage['examples'][number]): ExampleLine {
+	const command = example.arguments ? `pnpm josh ${name} ${example.arguments}` : `pnpm josh ${name}`
+
+	return { command, note: example.note }
+}
+
+// Every comment starts in one column, so a block reads as a table of what each spelling does.
+function format_examples(name: string, usage: CommandUsage): string {
+	const lines = usage.examples.map((example) => example_line(name, example))
+	const width = Math.max(...lines.map((line) => line.command.length)) + NOTE_GAP
+	const rendered = lines.map((line) =>
+		line.note === undefined ? line.command : `${line.command.padEnd(width)}# ${line.note}`,
+	)
+
+	return ['```bash', ...rendered, '```'].join('\n')
+}
+
+function code_span(text: string): string {
+	return `\`${text}\``
+}
+
+function format_flags(flags: NonNullable<CommandUsage['flags']>): string {
+	const items = flags.map(
+		(flag) =>
+			`- ${flag.names.map((spelling) => code_span(spelling)).join(' / ')} — ${flag.description}`,
+	)
+
+	return ['**Options:**', '', ...items].join('\n')
+}
+
+function format_usage(name: string): string | undefined {
+	const usage = usage_for(name)
+	if (usage === undefined) return undefined
+	const flags = usage.flags === undefined ? [] : [format_flags(usage.flags)]
+
+	return [format_examples(name, usage), ...flags].join('\n\n')
+}
+
+// `josh help <command>`: the synopsis line, the description, then the usage block when the command
+// has one. An alias resolves to its command; a name that is neither answers `undefined`.
+function format_command_help(input: string): string | undefined {
+	const name = canonical_command(input)
+	const entry = Object.hasOwn(COMMAND_MAP, name) ? COMMAND_MAP[name] : undefined
+	if (entry === undefined) return undefined
+	const [synopsis] = entry.reference
+	const head = synopsis ? `josh ${name} ${synopsis}` : `josh ${name}`
+	const usage = format_usage(name)
+
+	return [head, '', entry.description, ...(usage === undefined ? [] : ['', usage])].join('\n')
+}
+
+// The commands whose usage blocks a reference page renders — the keys of the tables tied to it.
+function page_commands(page: string): Array<string> {
+	const tables = Object.hasOwn(USAGE_PAGE_TABLES, page) ? USAGE_PAGE_TABLES[page] : undefined
+
+	return (tables ?? []).flatMap((table) => Object.keys(table))
+}
+
+const command_usage = {
+	USAGE_PAGES: Object.keys(USAGE_PAGE_TABLES),
+	format_command_help,
+	format_usage,
+	page_commands,
+}
+
+export { command_usage }

package/scripts/josh/file-map-stamp.ts

@@ -211,9 +211,7 @@ function is_own_record(stamp: FileMapStamp): boolean {
 function complete_at(target: string): string | undefined {
 	const stamp = read_at(target)
 
-	if (stamp === undefined) return undefined
-
-	if (!is_own_record(stamp)) return undefined
+	if (stamp === undefined || !is_own_record(stamp)) return undefined
 
 	return stamp_file.write_stamp(target, { ...stamp, completed_at: new Date().toISOString() })
 }

package/scripts/josh/hook-decision.ts

@@ -87,8 +87,8 @@ function deny_envelope(reason: string): string {
 }
 
 // **A rewrite, not a refusal**: the call proceeds with `updated_input` merged
-// over its own. `allow` is the decision the harness applies an `updatedInput` under; a settings `deny`
-// rule still wins over it, so this never widens what the call may do.
+// over its own and is allowed past the permission prompt; a settings `deny` rule still wins over it.
+// Where the line may carry commands the hook did not write, `flow_rewrite_envelope` is the one to use.
 function rewrite_envelope(updated_input: Record<string, unknown>, context: string): string {
 	return JSON.stringify({
 		systemMessage: context,
@@ -101,6 +101,20 @@ function rewrite_envelope(updated_input: Record<string, unknown>, context: strin
 	})
 }
 
+// **A rewrite that leaves the permission to the harness.** No `permissionDecision`, so the rewritten
+// call meets the same permission flow the typed one would have — whatever else rides the line beside
+// the rewritten part is prompted for, or not, exactly as before (joshuafolkken/kit#3875).
+function flow_rewrite_envelope(updated_input: Record<string, unknown>, context: string): string {
+	return JSON.stringify({
+		systemMessage: context,
+		hookSpecificOutput: {
+			hookEventName: HOOK_EVENT_NAME,
+			updatedInput: updated_input,
+			additionalContext: context,
+		},
+	})
+}
+
 // **A notice, not a decision.** It carries no `permissionDecision`, so the call proceeds exactly as it
 // would have; `additionalContext` is what reaches the model, and `systemMessage` is what the person
 // watching sees. Both are filled because either channel alone leaves one of the two blind — and the
@@ -476,6 +490,7 @@ const hook_decision = {
 	deny_envelope,
 	emit_outcome,
 	fault_notice,
+	flow_rewrite_envelope,
 	is_switch_enabled,
 	is_switch_opt_in,
 	load_environment_file,

package/scripts/josh/josh-command-map.ts

@@ -77,6 +77,7 @@ const ALIASES: Record<string, string> = {
 	tm: 'time',
 	tmd: 'time:density',
 	rtr: 'retrospective',
+	ca: 'cost:audit',
 	rvf: 'review:findings',
 	ruv: 'rule:value',
 	ev: 'eval',
@@ -86,6 +87,7 @@ const ALIASES: Record<string, string> = {
 	lst: 'lane:stats',
 	lli: 'lane:limit',
 	lrs: 'lane:restart',
+	lwd: 'lane:withdraw',
 	blr: 'backlogrun',
 }
 

package/scripts/josh/josh-command-types.ts

@@ -43,6 +43,25 @@ type CommandReference = readonly [
 	side_effects: ReadonlyArray<CommandSideEffect>,
 ]
 
+// One `pnpm josh <command> <arguments>` line of a usage block, with the comment printed after it.
+interface CommandExample {
+	arguments: string
+	note?: string
+}
+
+// Spellings of one option — `-y` and `--yes` — rendered side by side.
+interface CommandFlag {
+	names: ReadonlyArray<string>
+	description: string
+}
+
+// What `josh help <command>` prints and what the reference pages render between their usage
+// markers — one source for both, so the page and the terminal cannot disagree (#3932).
+interface CommandUsage {
+	examples: ReadonlyArray<CommandExample>
+	flags?: ReadonlyArray<CommandFlag>
+}
+
 interface CommandEntry {
 	script?: string
 	shell?: ReadonlyArray<string>
@@ -109,6 +128,13 @@ const TS_BUILD_INFO_FILE = '.tsbuildinfo'
 const CSPELL_CACHE_FILE = '.cspellcache'
 const ESLINT_EDIT_CACHE_FILE = '.eslintcache.edit'
 const ESLINT_RELATED_CACHE_FILE = '.eslintcache.related'
+const PRETTIER_CACHE_FILE = '.prettiercache'
+const PRETTIER_RELATED_CACHE_FILE = '.prettiercache.related'
+// The pre-commit hook's own, because a staged-files run on the gate's file degrades it: cspell prunes
+// every entry the run did not visit (measured 892 KB down to 18 KB), and `eslint --quiet` stores a
+// report without its warnings under the same config hash the gate reads.
+const CSPELL_COMMIT_CACHE_FILE = '.cspellcache.commit'
+const ESLINT_COMMIT_CACHE_FILE = '.eslintcache.commit'
 
 type GateCachePortability = 'raw' | 'rooted-json'
 
@@ -139,6 +165,10 @@ const ESLINT_RELATED_CACHE_SPEC: GateCacheSpec = {
 	cache_file: ESLINT_RELATED_CACHE_FILE,
 	portability: ROOTED_JSON_PORTABILITY,
 }
+// **Prettier's caches are in neither list: they do not survive a move to another checkout.**
+// Prettier 3 hashes each file's resolved options, *its absolute `filepath` included*, into the entry,
+// so rebasing the keys as ESLint's are still leaves every entry a miss — two checkouts of one tree
+// were measured sharing none of their 3,526 option hashes. Each checkout keeps a warm cache of its own.
 const GATE_CACHE_SPECS: ReadonlyArray<GateCacheSpec> = [
 	ESLINT_CACHE_SPEC,
 	TS_CACHE_SPEC,
@@ -175,14 +205,20 @@ const GATE_CACHE_FILES: ReadonlyArray<string> = GATE_CACHE_SPECS.map((spec) => s
 //
 // **The lint's target scope is untouched.** This is where a cache is written, not what is read:
 // `josh lint:related` narrows in front of the gate and `josh gate` still runs `josh lint` over the
-// whole tree before any commit.
+// whole tree before any commit. The scoped lint's prettier cache is its own for the same reason:
+// prettier rewrites its cache file whole as well.
 // What the ignore rules are asserted against: every cache file this package writes, wherever it is
-// written from. The gate's three, the edit hook's, and the scoped lint's — a cache file that is not
-// ignored is committed, or spell-checked, which is a red gate with nothing misspelled in the tree.
+// written from. The gate's, the edit hook's, the scoped lint's and the pre-commit hook's — a cache
+// file that is not ignored is committed, or spell-checked, which is a red gate with nothing
+// misspelled in the tree.
 const IGNORED_CACHE_FILES: ReadonlyArray<string> = [
 	...GATE_CACHE_FILES,
 	ESLINT_EDIT_CACHE_FILE,
 	ESLINT_RELATED_CACHE_FILE,
+	PRETTIER_CACHE_FILE,
+	PRETTIER_RELATED_CACHE_FILE,
+	CSPELL_COMMIT_CACHE_FILE,
+	ESLINT_COMMIT_CACHE_FILE,
 ]
 
 // `--cache --cache-strategy content` is one convention rather than two coincidences: cspell adopted
@@ -190,11 +226,11 @@ const IGNORED_CACHE_FILES: ReadonlyArray<string> = [
 const CONTENT_CACHE_FLAGS = ['--cache', '--cache-strategy', 'content'] as const
 const CACHE_LOCATION_FLAG = '--cache-location'
 
-// Four locations are written with these same four flags — the gate's eslint cache, the scoped lint's,
-// the edit hook's and the spell check's — so the sequence is built here once. Spelled out per
-// location, a fix to the order would have to be made four times and each copy fails silently: a flag
-// and its value are one unit, and a wrong order makes the tool read `--cache-strategy` as the file
-// name rather than erroring.
+// Every location is written with these same four flags — the eslint, prettier and spell-check caches
+// of the gate, the scoped lint, the edit hook and the pre-commit hook — so the sequence is built here
+// once. Spelled out per location, a fix to the order would have to be made once per location and
+// each copy fails silently: a flag and its value are one unit, and a wrong order makes the tool read
+// `--cache-strategy` as the file name rather than erroring.
 function content_cache_flags(cache_file: string): ReadonlyArray<string> {
 	return [...CONTENT_CACHE_FLAGS, CACHE_LOCATION_FLAG, cache_file]
 }
@@ -204,8 +240,12 @@ const ESLINT_EDIT_CACHE_FLAGS = content_cache_flags(ESLINT_EDIT_CACHE_FILE)
 const ESLINT_RELATED_CACHE_FLAGS = content_cache_flags(ESLINT_RELATED_CACHE_FILE)
 const TS_CACHE_FLAGS = ['--incremental', '--tsBuildInfoFile', TS_BUILD_INFO_FILE] as const
 const CSPELL_CACHE_FLAGS = content_cache_flags(CSPELL_CACHE_FILE)
+const PRETTIER_CACHE_FLAGS = content_cache_flags(PRETTIER_CACHE_FILE)
+const PRETTIER_RELATED_CACHE_FLAGS = content_cache_flags(PRETTIER_RELATED_CACHE_FILE)
+const CSPELL_COMMIT_CACHE_FLAGS = content_cache_flags(CSPELL_COMMIT_CACHE_FILE)
+const ESLINT_COMMIT_CACHE_FLAGS = content_cache_flags(ESLINT_COMMIT_CACHE_FILE)
 
-export type { CommandCategory, CommandEntry, GateCacheSpec }
+export type { CommandCategory, CommandEntry, CommandUsage, GateCacheSpec }
 // The three cache files are exported one by one as well as as a list, because `josh bench` clears
 // them per target: the lint step writes only the eslint one, so a target
 // that cleared the list would report a cold type check as the lint's own cost. The edit hook's cache
@@ -216,8 +256,10 @@ export {
 	COMMAND_SIDE_EFFECTS,
 	CSPELL_CACHE_FILE,
 	CSPELL_CACHE_FLAGS,
+	CSPELL_COMMIT_CACHE_FLAGS,
 	ESLINT_CACHE_FILE,
 	ESLINT_CACHE_FLAGS,
+	ESLINT_COMMIT_CACHE_FLAGS,
 	ESLINT_EDIT_CACHE_FLAGS,
 	ESLINT_RELATED_CACHE_FLAGS,
 	ESLINT_RELATED_CACHE_FILE,
@@ -226,6 +268,10 @@ export {
 	GATE_COMMAND,
 	IGNORED_CACHE_FILES,
 	OPTIONAL_ENV_FILE_FLAGS,
+	PRETTIER_CACHE_FILE,
+	PRETTIER_CACHE_FLAGS,
+	PRETTIER_RELATED_CACHE_FILE,
+	PRETTIER_RELATED_CACHE_FLAGS,
 	SHARED_CACHE_SPECS,
 	TS_BUILD_INFO_FILE,
 	TS_CACHE_FLAGS,

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

@@ -1,3 +1,4 @@
+import { core_budget } from '#scripts/gate/core-budget'
 import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
 import { BACKLOG_COMMANDS } from './josh-commands-backlog'
 import { DOCUMENT_COMMANDS } from './josh-commands-document'
@@ -80,6 +81,16 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['(--cut | --over <tokens-per-request>) [--path <dir>]', 'automation', ['none']],
 	},
+	'cost:audit': {
+		script: 'scripts/cost-audit/cost-audit-cli.ts',
+		description:
+			'Report AI cost over a period by session kind, tool category and guard, with cost per merge and regressions against the period before',
+		category: 'AI tools',
+		reference: ['[--period <days>]', 'maintainer', ['none']],
+		// Kit-only: it reads kit's own transcript store, like `josh retrospective`, which carries its
+		// summary line.
+		is_kit_only: true,
+	},
 	...DOCUMENT_COMMANDS,
 	time: {
 		script: 'scripts/time/time-cli.ts',
@@ -108,6 +119,8 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 			"Aggregate a finished run's cost, review findings, observation ledger and events into one digest",
 		category: 'AI tools',
 		reference: ['', 'maintainer', ['none']],
+		core_weight: core_budget.CORE_WEIGHTS.retrospective,
+		memory_mb: core_budget.MEMORY_MB.retrospective,
 		// Kit-only: it reads kit's own development run — the transcript store, the review ledger and the
 		// run event stream — so it means nothing in a consumer project and is dropped from a consumer's
 		// help, through the same declaration `josh time` uses for the same reason.

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

@@ -129,7 +129,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 	'stop:guard': {
 		script: 'scripts/hooks/stop-guard.ts',
 		description:
-			'Claude Code Stop hook: deliver the three stop-time rules — hold notify/release and issue citation (reads the Stop payload on stdin)',
+			'Claude Code Stop hook: send the hold notify, release the hold and print the issue citations itself; block on the rules that need the model (reads the Stop payload on stdin)',
 		category: 'Development',
 		reference: ['', 'automation', ['none']],
 		// **No `tsx_arguments`, deliberately**, the same as `pretool:guard` above: this runs at every

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

@@ -19,6 +19,12 @@ const HOOKS_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Git hooks',
 		reference: ['[paths...]', 'automation', ['none']],
 	},
+	'pre-commit-lint': {
+		script: 'scripts/hooks/pre-commit-lint.ts',
+		description: 'Git hook: run cspell, prettier or eslint over staged files from a content cache',
+		category: 'Git hooks',
+		reference: ['<cspell|prettier|eslint> [paths...]', 'automation', ['files']],
+	},
 	'pre-push-unit': {
 		script: 'scripts/hooks/pre-push-unit.ts',
 		description: 'Git hook: run unit tests, reusing a green gate recorded on the pushed tree',

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

@@ -83,6 +83,15 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['<issue>', 'developer', ['files', 'git', 'processes', 'network']],
 	},
+	// `.env` is read for `JOSH_LANE_ROOT`, as every lane command reads it, so the lane is found.
+	'lane:withdraw': {
+		script: 'scripts/lane/lane-withdraw-cli.ts',
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		description:
+			'Stop a running lane child, stash its uncommitted work, close its issue as not planned and close the lane — booked withdrawn, not as an outage or a failure',
+		category: 'AI tools',
+		reference: ['<issue> --reason <text>', 'developer', ['files', 'git', 'processes', 'network']],
+	},
 	// A live run's lane limit: `.env` is read so the bare form reports the
 	// `JOSH_LANE_LIMIT` a person set there when no override stands.
 	'lane:limit': {
@@ -106,7 +115,7 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 	'lane:stats': {
 		...MEASURE_ARGUMENTS,
 		description:
-			'Print one table row of lane throughput, gate duration and machine load over a period, the per-stage durations of a lane under it, and the wait after each ship stop reason under those',
+			'Print one table row of lane throughput, gate duration and machine load over a period, the per-stage durations of a lane under it, the wait after each ship stop reason under those, and the duration and reuse count of each gate check last',
 		category: 'AI tools',
 		reference: ['--period <days> [--limit <lane-limit>]', 'maintainer', ['none']],
 		default_script_arguments: ['stats'],

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

@@ -112,6 +112,11 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 	// A script rather than an `sh -c` chain, because the strategy has to be named rather than left to
 	// the caller's git configuration: a bare `git pull` aborts with `Need to specify how to reconcile
 	// divergent branches` on exactly the diverged branch the command exists for.
+	//
+	// **It declares no core weight, by measurement** (joshuafolkken/kit#3944): its own work is git, and
+	// the catalog it may regenerate took 0.6s of CPU. The heavy processes seen beside it are commit
+	// hooks — its regenerated catalog's commit runs them — which reserve themselves, and a weight here
+	// would set the held mark they inherit, folding the parallel hook tools into this one place.
 	'main:merge': {
 		script: 'scripts/git/main-merge.ts',
 		description: 'Merge origin default branch into the current branch',

package/scripts/josh/josh-logic.ts

@@ -3,7 +3,6 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { resolve_local_bin, resolve_package_bin } from '#scripts/build/local-bin'
 import { core_budget } from '#scripts/gate/core-budget'
-import { ancestor_directories } from '#scripts/lib/ancestor-directories'
 import { package_version_schema } from '#scripts/lib/schemas'
 import { resolve_spawn_exit } from '#scripts/lib/spawn-exit'
 import { execaSync } from 'execa'
@@ -18,6 +17,7 @@ import {
 import { composite_arguments, USAGE_ERROR_EXIT_CODE } from './josh-composite-arguments'
 import { josh_in_process } from './josh-in-process'
 import { kit_only } from './kit-only'
+import { find_package_directory } from './package-directory'
 import { run_github_prerequisite } from './run-github-prerequisite'
 
 const COLUMN_WIDTH = 26
@@ -35,17 +35,6 @@ interface TsxRunner {
 	leading_arguments: ReadonlyArray<string>
 }
 
-// Resolve the kit package root by ascending to the nearest package.json. This works both
-// from the bundled dist/josh.js (one level under the root) and from the tsx source at
-// scripts/josh/ (two levels), so this file's depth no longer has to be hard-coded.
-function find_package_directory(start_directory: string): string {
-	return (
-		ancestor_directories.nearest(start_directory, (directory) =>
-			existsSync(path.join(directory, PACKAGE_JSON)),
-		) ?? start_directory
-	)
-}
-
 const PACKAGE_DIR = find_package_directory(path.dirname(fileURLToPath(import.meta.url)))
 
 function resolve_tsx_executable(): string {
@@ -287,6 +276,7 @@ function declared(value: number | (() => number) | undefined): number | undefine
 // without claiming a place. A command under a parent that already holds its cores claims nothing:
 // `core_budget.with_command_reservation` reads the mark that parent set.
 async function dispatch_entry(
+	command: string,
 	entry: CommandEntry,
 	subcommand_arguments: Array<string>,
 ): Promise<number> {
@@ -297,7 +287,7 @@ async function dispatch_entry(
 	return await core_budget.with_command_reservation(
 		weight,
 		async () => await run_entry(entry, subcommand_arguments),
-		{ memory_mb: declared(entry.memory_mb) },
+		{ memory_mb: declared(entry.memory_mb), command },
 	)
 }
 
@@ -314,7 +304,7 @@ async function run_command(
 	const early_exit = pre_dispatch_exit(resolved, entry, subcommand_arguments, is_consumer)
 	if (early_exit !== undefined) return early_exit
 
-	return await dispatch_entry(entry, subcommand_arguments)
+	return await dispatch_entry(resolved, entry, subcommand_arguments)
 }
 
 const josh_logic = {
@@ -330,10 +320,11 @@ export { ALIASES, COMMAND_MAP } from './josh-command-map'
 export { SPAWN_ERROR_EXIT_CODE } from '#scripts/lib/spawn-exit'
 export { composite_arguments, USAGE_ERROR_EXIT_CODE } from './josh-composite-arguments'
 export {
-	find_package_directory,
 	josh_logic,
 	resolve_alias,
 	resolve_tsx_executable,
 	resolve_tsx_runner,
 	UNKNOWN_COMMAND_EXIT_CODE,
 }
+
+export { find_package_directory } from './package-directory'

package/scripts/josh/josh-usage-automation.ts

@@ -0,0 +1,121 @@
+import type { CommandUsage } from './josh-command-types'
+
+// The usage of the commands `docs/josh-commands-automation.md` documents under "Development",
+// "Project" and "AI tools", keyed by command name. The page's usage blocks are generated from this
+// table and `josh help <command>` prints it, so an example or a flag is written once, here (#3939).
+const STAGED = '--staged'
+const JSON_FLAG = '--json'
+const BRANCH_DIFF = 'the branch diff'
+const STAGED_DIFF = 'the staged diff instead'
+const PR_NUMBER = '42'
+const DRY_RUN = '--dry-run'
+const SKIP_PUBLISH_WAIT = '--skip-publish-wait'
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const AUTOMATION_USAGE: Readonly<Record<string, CommandUsage>> = {
+	'refactor:scan': { examples: [{ arguments: '' }] },
+	'time:density': {
+		examples: [{ arguments: '' }, { arguments: '--lanes 5', note: 'the five most recent lanes' }],
+		flags: [
+			{
+				names: ['--lanes <n>'],
+				description: 'average over a different count of recent qualifying lanes (default 10).',
+			},
+			{
+				names: ['--path <dir>'],
+				description:
+					"read another project's lane transcripts, as `josh time` does. Run it from the main checkout — a lane reads only its own transcript.",
+			},
+		],
+	},
+	'e2e:retry-check': { examples: [{ arguments: '' }] },
+	'sync:scope': {
+		examples: [
+			{ arguments: '', note: BRANCH_DIFF },
+			{ arguments: STAGED, note: STAGED_DIFF },
+			{ arguments: JSON_FLAG, note: '{"scope":"managed","reason":"..."}' },
+		],
+		flags: [
+			{ names: [STAGED], description: 'inspect the staged diff instead of the branch diff.' },
+			{ names: [JSON_FLAG], description: 'emit `{"scope","reason"}` as JSON.' },
+		],
+	},
+	'dogfood:commit': { examples: [{ arguments: '~/Development/kit-test-html-start' }] },
+	'fresh:run': {
+		examples: [
+			{ arguments: '--list', note: "kit's six patterns" },
+			{ arguments: 'kit-test-html-init', note: 'one pattern, the packed checkout' },
+			{
+				arguments: 'kit-test-html-start',
+				note: 'a GitHub pattern, the latest published version',
+			},
+			{ arguments: '--spec fresh/html-init.json', note: 'a scenario another toolkit wrote' },
+		],
+		flags: [
+			{ names: ['--list'], description: 'print the pattern names and run nothing.' },
+			{
+				names: ['--spec <file.json>'],
+				description:
+					'run the scenario in this file instead of a named pattern; the path is relative to the project root.',
+			},
+			{
+				names: ['--package-version <version>'],
+				description:
+					"the published version a `package_source: published` scenario installs. Default: the registry's latest version of the package the command is run from.",
+			},
+			{
+				names: ['--log-dir <dir>'],
+				description: 'where the log is written. Default: `.claude/tmp/fresh-machine`.',
+			},
+			{ names: ['--rebuild'], description: 'build the machine image without the layer cache.' },
+		],
+	},
+	'auth:setup': {
+		examples: [
+			{ arguments: '', note: 'sign in and save the token' },
+			{ arguments: '--check', note: 'ok: … saved on <date>, or missing: … and exit 1' },
+		],
+	},
+	'sonar:hotspots': { examples: [{ arguments: PR_NUMBER }] },
+	'sonar:new-code': { examples: [{ arguments: PR_NUMBER }] },
+	'ui:routes': {
+		examples: [
+			{ arguments: '', note: BRANCH_DIFF },
+			{ arguments: STAGED, note: STAGED_DIFF },
+		],
+	},
+	propagate: {
+		examples: [
+			{ arguments: '' },
+			{ arguments: DRY_RUN, note: 'report targets and steps, write nothing' },
+			{ arguments: SKIP_PUBLISH_WAIT, note: 'release already known to be published' },
+			{ arguments: '--target app-kit', note: 'carry the release into one consumer only' },
+		],
+		flags: [
+			{
+				names: [DRY_RUN],
+				description:
+					'report targets and steps without writing; skips the publish wait, opens no issues.',
+			},
+			{
+				names: [SKIP_PUBLISH_WAIT],
+				description: 'skip the registry poll for an already-published release.',
+			},
+			{
+				names: ['--target <repo>'],
+				description:
+					'process only that consumer (`app-kit` or `joshuafolkken/app-kit`); the rest are reported `skipped` and left untouched. An unknown, ambiguous or non-dependent name fails before the publish wait, writing nothing.',
+			},
+		],
+	},
+	'repo:party': {
+		examples: [
+			{ arguments: 'joshuafolkken/kit', note: '→ first-party (in the kit session)' },
+			{ arguments: 'sveltejs/kit', note: '→ third-party' },
+			{ arguments: '', note: "no argument: the session's own repository" },
+		],
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { AUTOMATION_USAGE }