@joshuafolkken/kit 1.872.0

package/scripts/doctor/doctor-consumer.ts

@@ -0,0 +1,181 @@
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { read_spawn_stdout } from '#scripts/lib/spawn-exit'
+import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
+import { safe_json_parse } from '#scripts/version/parse-json'
+import { execaSync } from 'execa'
+import { z } from 'zod'
+
+// The consumer-setup checks `josh doctor` runs in a repository that installs kit (joshuafolkken/kit#1930).
+// Each failure was a way the distribution went silently wrong: the plugin never installed so skills
+// were missing, `core.hooksPath` set so lefthook installed nothing, the `CLAUDE.md` pointer resolving
+// to a file that is not there before `pnpm install`, and secretlint not runnable so the pre-commit
+// hook could not scan. Each check prints a one-line verdict; none of them fails the command.
+
+const NODE_MODULES = 'node_modules'
+const SETTINGS_PATH = path.join('.claude', 'settings.json')
+const CLAUDE_MD = 'CLAUDE.md'
+const PLUGIN_ID = 'kit@kit'
+// The one line a consumer's CLAUDE.md is: an import of the packaged rules. kit's own CLAUDE.md is the
+// full document, so this pointer is also what tells a consumer repository apart from kit itself.
+const CLAUDE_MD_POINTER = `@${NODE_MODULES}/${KIT_PACKAGE_NAME}/dist/${CLAUDE_MD}`
+const SECRETLINT_BIN = path.join(NODE_MODULES, '.bin', 'secretlint')
+const GIT_TIMEOUT_MS = 2000
+
+const manifest_schema = z.object({
+	name: z.string().optional(),
+	dependencies: z.record(z.string(), z.string()).optional(),
+	devDependencies: z.record(z.string(), z.string()).optional(),
+})
+const settings_schema = z.object({
+	enabledPlugins: z.record(z.string(), z.boolean()).optional(),
+})
+type ManifestShape = z.infer<typeof manifest_schema>
+const STATE_OK = 'ok'
+const STATE_TARGET_MISSING = 'target-missing'
+const STATE_MISSING = 'missing'
+type ClaudeMdState = typeof STATE_OK | typeof STATE_TARGET_MISSING | typeof STATE_MISSING
+
+function read_optional(file_path: string): string | undefined {
+	try {
+		return existsSync(file_path) ? readFileSync(file_path, 'utf8') : undefined
+	} catch {
+		return undefined
+	}
+}
+
+function parse_manifest(root: string): ManifestShape | undefined {
+	const content = read_optional(path.join(root, 'package.json'))
+	if (content === undefined) return undefined
+	const parsed = manifest_schema.safeParse(safe_json_parse(content))
+
+	return parsed.success ? parsed.data : undefined
+}
+
+function lists_kit_dependency(manifest: ManifestShape | undefined): boolean {
+	if (manifest === undefined) return false
+
+	return (
+		Object.hasOwn(manifest.dependencies ?? {}, KIT_PACKAGE_NAME) ||
+		Object.hasOwn(manifest.devDependencies ?? {}, KIT_PACKAGE_NAME)
+	)
+}
+
+// Whether this repository consumes kit rather than being kit itself. kit is excluded by its own
+// package name; a consumer either declares the dependency or already has it installed, so a fresh
+// clone before `pnpm install` (which declares it) still counts.
+function is_kit_consumer(root: string): boolean {
+	const manifest = parse_manifest(root)
+	if (manifest?.name === KIT_PACKAGE_NAME) return false
+
+	return (
+		lists_kit_dependency(manifest) || existsSync(path.join(root, NODE_MODULES, KIT_PACKAGE_NAME))
+	)
+}
+
+function is_plugin_declared(root: string): boolean {
+	const content = read_optional(path.join(root, SETTINGS_PATH))
+	if (content === undefined) return false
+	const parsed = settings_schema.safeParse(safe_json_parse(content))
+
+	return parsed.success && parsed.data.enabledPlugins?.[PLUGIN_ID] === true
+}
+
+// The value of `core.hooksPath`, or undefined when it is unset. A set value is what stops lefthook
+// from installing kit's git hooks — the failure is silent but for one stderr line.
+function configured_hooks_path(root: string): string | undefined {
+	const result = execaSync('git', ['-C', root, 'config', '--get', 'core.hooksPath'], {
+		reject: false,
+		timeout: GIT_TIMEOUT_MS,
+	})
+	const value = read_spawn_stdout(result).trim()
+
+	return value === '' ? undefined : value
+}
+
+function claude_md_state(root: string): ClaudeMdState {
+	const content = read_optional(path.join(root, CLAUDE_MD))
+	if (content === undefined) return STATE_MISSING
+	if (!content.includes(CLAUDE_MD_POINTER)) return STATE_OK
+
+	return existsSync(path.join(root, NODE_MODULES, KIT_PACKAGE_NAME, 'dist', CLAUDE_MD))
+		? STATE_OK
+		: STATE_TARGET_MISSING
+}
+
+function is_secretlint_runnable(root: string): boolean {
+	return existsSync(path.join(root, SECRETLINT_BIN))
+}
+
+function status_line(is_ok: boolean, ok_text: string, warn_text: string): string {
+	return is_ok ? `  ✓ ${ok_text}` : `  ⚠ ${warn_text}`
+}
+
+function plugin_line(is_declared: boolean): string {
+	return status_line(
+		is_declared,
+		`kit plugin declared (run \`claude plugin install ${PLUGIN_ID}\` once if skills are missing)`,
+		'kit plugin not declared in .claude/settings.json — run `pnpm josh sync`',
+	)
+}
+
+function hooks_path_line(hooks_path: string | undefined): string {
+	return status_line(
+		hooks_path === undefined,
+		'git hooks install normally (core.hooksPath unset)',
+		`core.hooksPath is set (${hooks_path ?? ''}) — lefthook installs no git hooks; unset it`,
+	)
+}
+
+function claude_md_line(state: ClaudeMdState): string {
+	if (state === STATE_OK) return '  ✓ CLAUDE.md resolves to the installed kit rules'
+
+	if (state === STATE_TARGET_MISSING) {
+		return '  ⚠ CLAUDE.md points at rules that are not installed — run `pnpm install`'
+	}
+
+	return '  ⚠ CLAUDE.md is missing — run `pnpm josh init`'
+}
+
+function secretlint_line(is_runnable: boolean): string {
+	return status_line(
+		is_runnable,
+		'secretlint is runnable',
+		'secretlint is not installed — run `pnpm install`',
+	)
+}
+
+function consumer_setup_lines(root: string): ReadonlyArray<string> {
+	return [
+		plugin_line(is_plugin_declared(root)),
+		hooks_path_line(configured_hooks_path(root)),
+		claude_md_line(claude_md_state(root)),
+		secretlint_line(is_secretlint_runnable(root)),
+	]
+}
+
+// Printed only in a repository that consumes kit, so kit's own `josh doctor` stays quiet about it.
+function report_consumer_setup(root: string): void {
+	if (!is_kit_consumer(root)) return
+
+	console.info('')
+	console.info('Consumer setup:')
+	for (const line of consumer_setup_lines(root)) console.info(line)
+}
+
+const doctor_consumer = {
+	claude_md_line,
+	claude_md_state,
+	configured_hooks_path,
+	consumer_setup_lines,
+	hooks_path_line,
+	is_kit_consumer,
+	is_plugin_declared,
+	is_secretlint_runnable,
+	plugin_line,
+	report_consumer_setup,
+	secretlint_line,
+}
+
+export type { ClaudeMdState }
+export { doctor_consumer }

package/scripts/doctor/doctor-io.ts

@@ -0,0 +1,210 @@
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { read_spawn_stderr, read_spawn_stdout } from '#scripts/lib/spawn-exit'
+import { execaSync } from 'execa'
+import { doctor_logic } from './doctor-logic'
+
+const JOSH_BIN = 'josh'
+const GIT_TIMEOUT_MS = 2000
+const NOT_A_REPOSITORY_MESSAGE = 'not a git repository'
+const NPM_VERSION_UPDATES_DISABLED = 'open-pull-requests-limit: 0'
+const DEPENDABOT_CONFIG_PATH = '.github/dependabot.yml'
+const ECOSYSTEM_KEY = 'package-ecosystem:'
+const NPM_ECOSYSTEM = 'npm'
+const AUTO_MERGE_WORKFLOW_PATH = '.github/workflows/dependabot-auto-merge.yml'
+// The command that needs the repository's "Allow auto-merge" setting, and the only thing in the
+// workflow that does. Matching it rather than the filename is what keeps the report tied to the
+// prerequisite: a file of that name which never calls `--auto` creates no prerequisite, and a
+// consumer's own auto-merge workflow which does creates the same one kit's does
+// (joshuafolkken/kit#834).
+const AUTO_MERGE_COMMAND = 'gh pr merge --auto'
+const YAML_COMMENT_PREFIX = '#'
+
+// Resolve the `josh` that the shell would run — the first match on PATH, via the platform's
+// lookup command (`where` on Windows, `which` elsewhere). Undefined when the lookup fails or
+// prints nothing (no `josh` on PATH, e.g. inside the kit repo where only `pnpm josh` runs).
+function resolve_path_josh(): string | undefined {
+	const lookup = doctor_logic.path_lookup_command(process.platform)
+	const result = execaSync(lookup, [JOSH_BIN], { reject: false })
+
+	return doctor_logic.first_path_line(read_spawn_stdout(result))
+}
+
+// Resolve the pnpm-global `josh` bin path. Undefined when pnpm is missing or the global bin does
+// not contain a `josh` (kit not installed globally). `pnpm bin -g` prepends a `[WARN]` line to
+// stdout inside a project, so the bin directory is extracted via first_path_line.
+function resolve_pnpm_global_josh(): string | undefined {
+	const result = execaSync('pnpm', ['bin', '-g'], { reject: false })
+	const bin_directory = doctor_logic.first_path_line(read_spawn_stdout(result))
+	if (bin_directory === undefined) return undefined
+	const candidate = path.join(bin_directory, JOSH_BIN)
+
+	return existsSync(candidate) ? candidate : undefined
+}
+
+// Whether the working directory is provably *outside* a git work tree. Purely local — no network,
+// and it does not depend on `gh` being installed or authenticated, which is what makes it usable to
+// decide whether a repository-scoped check applies at all (joshuafolkken/kit#805).
+//
+// An empty root from a successful run is not an answer, so it is undetermined rather than inside.
+function classify_top_level(top_level: string): GitTopLevel {
+	return top_level === '' ? { state: 'undetermined' } : { state: 'inside', top_level }
+}
+
+// Only `fatal: not a git repository` proves absence. Exit 128 alone does not: git returns it inside
+// a repository for dubious ownership (`safe.directory`), a corrupt `.git`, or a broken config. An
+// undefined exit code is a spawn failure or a timeout — git never answered at all.
+function classify_git_failure(exit_code: number | undefined, stderr: string): GitTopLevel {
+	if (exit_code === undefined) return { state: 'undetermined' }
+
+	return { state: stderr.includes(NOT_A_REPOSITORY_MESSAGE) ? 'outside' : 'undetermined' }
+}
+
+// The repository root, or a reason there is none. `--show-toplevel` is used rather than
+// `--is-inside-work-tree` because the caller needs the root itself: the config file that decides
+// applicability lives at a fixed path relative to it, and resolving that path against the working
+// directory instead would skip the check in every subdirectory of a consumer repository.
+//
+// `outside` and `undetermined` are kept apart deliberately: only proof of absence may skip the
+// caller's check, because reporting an unknown as a clean result is the false all-clear
+// joshuafolkken/kit#805 exists to remove. See the two classifiers above for what proves what.
+function resolve_git_top_level(): GitTopLevel {
+	const result = execaSync('git', ['rev-parse', '--show-toplevel'], {
+		reject: false,
+		timeout: GIT_TIMEOUT_MS,
+		// git translates its messages, so the match below would fail under any non-English locale and
+		// the spurious warning would come back. `C` pins the output this code was written against.
+		env: { LC_ALL: 'C', LANGUAGE: 'C' },
+		extendEnv: true,
+	})
+
+	if (result.exitCode === 0) return classify_top_level(read_spawn_stdout(result).trim())
+
+	return classify_git_failure(result.exitCode, read_spawn_stderr(result))
+}
+
+// Whether one line is the setting itself rather than prose about it. kit's own template explains the
+// option in a comment containing the same literal, so a substring search over the file would match
+// that comment — and any file that quotes it. The line must be indented (it sits under an `updates:`
+// entry) and must be exactly the mapping, which a `#` comment never is. Scanned line by line rather
+// than matched with an anchored regex, which backtracks super-linearly on this shape.
+function is_version_updates_disabled_line(line: string): boolean {
+	if (!line.startsWith(' ') && !line.startsWith('\t')) return false
+
+	return line.trim() === NPM_VERSION_UPDATES_DISABLED
+}
+
+// A Dependabot `updates:` entry begins with the ecosystem key; the limit must belong to the npm one.
+function is_entry_start(line: string): boolean {
+	return line.trimStart().startsWith(`- ${ECOSYSTEM_KEY}`)
+}
+
+function is_npm_entry_start(line: string): boolean {
+	return is_entry_start(line) && line.includes(NPM_ECOSYSTEM)
+}
+
+// The lines belonging to the npm `updates:` entry, in order. An entry runs until the next one starts.
+function npm_entry_lines(lines: ReadonlyArray<string>): Array<string> {
+	const start = lines.findIndex((line) => is_npm_entry_start(line))
+	if (start === -1) return []
+	const rest = lines.slice(start + 1)
+	const end = rest.findIndex((line) => is_entry_start(line))
+
+	return end === -1 ? rest : rest.slice(0, end)
+}
+
+// Whether the npm entry disables version updates. Scoped to that entry rather than matched across
+// the whole file: a project that sets the same limit on, say, its `docker` entry has not received
+// kit's change and must not be warned about it.
+function has_npm_version_updates_disabled(content: string): boolean {
+	return npm_entry_lines(content.split('\n')).some((line) => is_version_updates_disabled_line(line))
+}
+
+// The nearest ancestor of `start` holding `relative_path`, or nothing. Searching upward rather than
+// testing `start` alone is what keeps the check alive in a subdirectory when git could not report
+// the repository root — a `safe.directory` refusal, for instance, which `classify_git_failure`
+// deliberately routes to `undetermined` precisely so the check survives.
+//
+// `boundary` stops the walk at the repository root when one is known. Without it a repository nested
+// under a kit consumer would inherit the parent's files and be warned about a prerequisite that
+// belongs to a different project.
+function find_project_file(
+	start: string,
+	relative_path: string,
+	boundary: string | undefined,
+): string | undefined {
+	const candidate = path.join(start, relative_path)
+	if (existsSync(candidate)) return candidate
+	if (start === boundary) return undefined
+	const parent = path.dirname(start)
+
+	return parent === start ? undefined : find_project_file(parent, relative_path, boundary)
+}
+
+// Whether a distributed artifact is present *and* carries the marker that creates the prerequisite.
+// Existence alone is never enough: any project may ship a file of the same name, and warning there
+// would advertise an enabling command for a repository that never consumed kit.
+//
+// The read is guarded even though existence was just checked: a permission error, a directory in the
+// file's place, or a race between the two calls would otherwise throw out of `josh doctor` and abort
+// a command whose whole contract is that this check never fails it. An unreadable file cannot prove
+// the prerequisite applies, so it reads as absent.
+function has_marked_project_file(
+	start: string,
+	relative_path: string,
+	boundary: string | undefined,
+	is_marked: (content: string) => boolean,
+): boolean {
+	const file_path = find_project_file(start, relative_path, boundary)
+	if (file_path === undefined) return false
+
+	try {
+		return is_marked(readFileSync(file_path, 'utf8'))
+	} catch {
+		return false
+	}
+}
+
+// Whether the project has received kit's `.github/dependabot.yml`. The npm entry's
+// `open-pull-requests-limit: 0` is what creates the prerequisite (joshuafolkken/kit#803), so that is
+// what is matched.
+function has_distributed_dependabot_config(start: string, boundary?: string): boolean {
+	return has_marked_project_file(start, DEPENDABOT_CONFIG_PATH, boundary, (content) =>
+		has_npm_version_updates_disabled(content),
+	)
+}
+
+// Whether one line runs the command rather than merely mentioning it. kit's own template explains
+// the prerequisite in a comment containing the same literal, so a substring search over the file
+// would match that comment — and any file that quotes it. The same distinction the npm
+// version-updates check draws above, for the same reason.
+function is_auto_merge_command_line(line: string): boolean {
+	const trimmed = line.trimStart()
+
+	return !trimmed.startsWith(YAML_COMMENT_PREFIX) && trimmed.includes(AUTO_MERGE_COMMAND)
+}
+
+// Whether the project runs a Dependabot auto-merge workflow. `gh pr merge --auto` is what needs the
+// repository's "Allow auto-merge" setting, so that is what is matched (joshuafolkken/kit#834).
+function has_auto_merge_workflow(start: string, boundary?: string): boolean {
+	return has_marked_project_file(start, AUTO_MERGE_WORKFLOW_PATH, boundary, (content) =>
+		content.split('\n').some((line) => is_auto_merge_command_line(line)),
+	)
+}
+
+// Where a repository-scoped check stands: inside a repository (with its root), provably outside
+// one, or unable to tell.
+type GitTopLevel =
+	{ state: 'inside'; top_level: string } | { state: 'outside' } | { state: 'undetermined' }
+
+const doctor_io = {
+	GIT_TIMEOUT_MS,
+	resolve_path_josh,
+	resolve_pnpm_global_josh,
+	has_distributed_dependabot_config,
+	has_auto_merge_workflow,
+	resolve_git_top_level,
+}
+
+export type { GitTopLevel }
+export { doctor_io }

package/scripts/doctor/doctor-logic.ts

@@ -0,0 +1,122 @@
+import path from 'node:path'
+
+const RECOVERY_COMMAND = 'josh doctor --fix'
+const REPOSITORY_MAP_HEADING = 'Repositories (same owner, discovered next to this one):'
+const NO_REPOSITORIES_FOUND = '  (none discovered — see JOSH_REPO_PATHS in docs/josh-commands.md)'
+const GLOBAL_REINSTALL_COMMAND = 'pnpm add -g @joshuafolkken/kit'
+// Markers identifying a `josh` on PATH that was generated by an old kit `postinstall`
+// (pre-0.200.0 `install-bin.ts` wrote a shim referencing the kit package / tsx runner).
+const KIT_SHIM_MARKERS: ReadonlyArray<string> = [
+	'@joshuafolkken/kit',
+	'@joshuafolkken+kit',
+	'install-bin',
+]
+
+type ReclaimAction = 'remove' | 'none'
+
+interface ReclaimDecision {
+	action: ReclaimAction
+	target?: string
+	reason: string
+}
+
+const NO_SHADOW_REASON = 'no PATH shadowing detected'
+const NOT_KIT_SHIM_REASON =
+	'the shadowing binary is not a kit shim — remove it manually if it is unexpected'
+const RECLAIM_REASON = 'reclaimed the global josh by removing the stale kit shim'
+
+const WINDOWS_PLATFORM = 'win32'
+// Absolute path on any platform: POSIX `/…`, Windows drive-letter `C:\…` / `C:/…`, or UNC `\\…`.
+// Detecting absoluteness by shape (not `path.sep`) keeps parsing correct regardless of the host OS.
+const ABSOLUTE_PATH_PATTERN = /^(?:\/|[a-zA-Z]:[/\\]|\\\\)/u
+
+function normalize_path(target: string): string {
+	return path.resolve(target)
+}
+
+// The cross-platform PATH-lookup command: `where` on Windows, `which` elsewhere.
+function path_lookup_command(platform: string): string {
+	return platform === WINDOWS_PLATFORM ? 'where' : 'which'
+}
+
+// Extract an absolute path from possibly noisy command output: `pnpm bin -g` prepends a
+// `[WARN] Using --global …` line to stdout when run inside a project, and `where` may list several
+// matches. Take the first line that looks like an absolute path (the effective one), skipping
+// noise. Undefined when no such line is present.
+function first_path_line(stdout: string): string | undefined {
+	return stdout
+		.split('\n')
+		.map((line) => line.trim())
+		.find((line) => ABSOLUTE_PATH_PATTERN.test(line))
+}
+
+// PATH shadowing: the `josh` first on PATH is not the pnpm-global install. Both paths must be known
+// for a comparison — an undefined side means we cannot prove shadowing, so report false.
+function is_shadowed(path_josh: string | undefined, global_josh: string | undefined): boolean {
+	if (path_josh === undefined || global_josh === undefined) return false
+
+	return normalize_path(path_josh) !== normalize_path(global_josh)
+}
+
+// A reclaimable kit shim references the kit package or the removed install-bin script in its body.
+function is_kit_shim(content: string): boolean {
+	return KIT_SHIM_MARKERS.some((marker) => content.includes(marker))
+}
+
+// Decide whether `doctor --fix` may safely remove the shadowing binary. Only a confirmed kit shim
+// is removed; any other shadowing binary is left untouched and reported for manual review.
+function decide_reclaim(
+	path_josh: string | undefined,
+	global_josh: string | undefined,
+	shim_content: string,
+): ReclaimDecision {
+	if (!is_shadowed(path_josh, global_josh)) return { action: 'none', reason: NO_SHADOW_REASON }
+	// is_shadowed already guarantees path_josh is defined; this narrows the type for the return.
+	if (path_josh === undefined) return { action: 'none', reason: NO_SHADOW_REASON }
+	if (!is_kit_shim(shim_content)) return { action: 'none', reason: NOT_KIT_SHIM_REASON }
+
+	return { action: 'remove', target: path_josh, reason: RECLAIM_REASON }
+}
+
+// The discovered map, as `josh doctor` prints it. Printing it is what makes a wrong map noticeable:
+// the map decides which checkouts other commands write to, and a silent one would only be found by
+// the write landing in the wrong place (joshuafolkken/kit#869).
+function format_repository_map(map: ReadonlyMap<string, string>): string {
+	if (map.size === 0) return [REPOSITORY_MAP_HEADING, NO_REPOSITORIES_FOUND].join('\n')
+	const rows: Array<string> = []
+
+	for (const [key, repository_path] of map) rows.push(`  ${key}  ${repository_path}`)
+	const sorted = rows.toSorted((left, right) => left.localeCompare(right))
+
+	return [REPOSITORY_MAP_HEADING, ...sorted].join('\n')
+}
+
+function format_shadow_warning(path_josh: string, global_josh: string): string {
+	return [
+		"⚠ PATH shadowing: the 'josh' first on PATH is not the pnpm-global install.",
+		`  On PATH:     ${path_josh}`,
+		`  pnpm global: ${global_josh}`,
+		`  Recover:     ${RECOVERY_COMMAND}`,
+	].join('\n')
+}
+
+const doctor_logic = {
+	RECOVERY_COMMAND,
+	GLOBAL_REINSTALL_COMMAND,
+	NO_SHADOW_REASON,
+	NOT_KIT_SHIM_REASON,
+	RECLAIM_REASON,
+	REPOSITORY_MAP_HEADING,
+	NO_REPOSITORIES_FOUND,
+	format_repository_map,
+	normalize_path,
+	path_lookup_command,
+	first_path_line,
+	is_shadowed,
+	is_kit_shim,
+	decide_reclaim,
+	format_shadow_warning,
+}
+
+export type { ReclaimAction, ReclaimDecision }
+export { doctor_logic }

package/scripts/doctor/doctor-ports.ts

@@ -0,0 +1,117 @@
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { ENV_FILE_NAME, PORT_SEED_KEY, ports } from '#ports'
+import { lane_environment } from '#scripts/lane/lane-environment'
+
+// Each discovered repository's port seed and the dev / preview ports it resolves to, plus which
+// repositories share a seed (joshuafolkken/kit#1494).
+//
+// The formula `seed × 10 + lane` makes distinct seeds occupy disjoint bands, but two repositories on
+// the *same* seed still collide — as do the many that never set one and sit together on seed 0. That
+// clash surfaces only as an E2E run failing to bind a port somewhere else, so `doctor` names it here
+// instead. **`.env` is never rewritten**: the seed is a personal, per-machine setting, so the report
+// points at the clash and a person resolves it.
+
+const HEADING = 'Port seeds (dev / preview, and repositories sharing one):'
+const UNREADABLE = 'PORT_SEED could not be read'
+const ROW_INDENT = '  '
+const COLUMN_SEPARATOR = '  '
+const SHARED_PREFIX = '  ⚠ seed '
+const SOLE_MEMBER = 1
+
+interface RepoPorts {
+	name: string
+	// `undefined` when the repository's `.env` holds a malformed seed — reported rather than guessed.
+	seed: number | undefined
+	development: number | undefined
+	preview: number | undefined
+}
+
+interface SharedSeed {
+	seed: number
+	names: Array<string>
+}
+
+// A repository is read at its main work tree (seat 0), so the ports reported are the ones it runs on
+// without a lane open, computed from the seed alone — a root `.env` should carry no `JOSH_LANE_SEAT`,
+// and honoring a stray one would move the reported ports off the main tree and hide a valid seed
+// behind a malformed seat. A missing `.env` is the common case — the unset seed CI and un-migrated
+// consumers use — and reads as seed 0; a malformed seed is caught and reported unreadable, naming
+// the one key that is actually wrong.
+function read_repository_ports(name: string, repository_path: string): RepoPorts {
+	const file = path.join(repository_path, ENV_FILE_NAME)
+	const content = existsSync(file) ? readFileSync(file, 'utf8') : ''
+
+	try {
+		const seed = lane_environment.read_root_seed(content)
+		const environment = { [PORT_SEED_KEY]: String(seed) }
+
+		return {
+			name,
+			seed,
+			development: ports.resolve_development_port(environment),
+			preview: ports.resolve_preview_port(environment),
+		}
+	} catch {
+		return { name, seed: undefined, development: undefined, preview: undefined }
+	}
+}
+
+function format_row(entry: RepoPorts): string {
+	if (entry.seed === undefined) return `${ROW_INDENT}${entry.name}${COLUMN_SEPARATOR}${UNREADABLE}`
+
+	const columns = `seed ${String(entry.seed)}${COLUMN_SEPARATOR}dev ${String(entry.development)}${COLUMN_SEPARATOR}preview ${String(entry.preview)}`
+
+	return `${ROW_INDENT}${entry.name}${COLUMN_SEPARATOR}${columns}`
+}
+
+function group_by_seed(entries: ReadonlyArray<RepoPorts>): Map<number, Array<string>> {
+	const by_seed = new Map<number, Array<string>>()
+
+	for (const { name, seed } of entries) {
+		if (seed === undefined) continue
+		by_seed.set(seed, [...(by_seed.get(seed) ?? []), name])
+	}
+
+	return by_seed
+}
+
+// Only seeds held by more than one repository are a clash worth naming.
+function shared_seeds(entries: ReadonlyArray<RepoPorts>): Array<SharedSeed> {
+	return [...group_by_seed(entries)]
+		.filter(([, names]) => names.length > SOLE_MEMBER)
+		.map(([seed, names]) => ({ seed, names }))
+		.toSorted((left, right) => left.seed - right.seed)
+}
+
+function format_shared(shared: ReadonlyArray<SharedSeed>): Array<string> {
+	return shared.map(
+		({ seed, names }) => `${SHARED_PREFIX}${String(seed)} is shared by: ${names.join(', ')}`,
+	)
+}
+
+function format_port_report(entries: ReadonlyArray<RepoPorts>): string {
+	const rows = entries.map((entry) => format_row(entry))
+	const shared = format_shared(shared_seeds(entries))
+
+	return [HEADING, ...rows, ...shared].join('\n')
+}
+
+// The map is `owner/repo` → absolute path; the rows are sorted by name so the report is stable.
+function report_port_seeds(map: ReadonlyMap<string, string>): string {
+	const entries = [...map]
+		.toSorted(([left], [right]) => left.localeCompare(right))
+		.map(([name, repository_path]) => read_repository_ports(name, repository_path))
+
+	return format_port_report(entries)
+}
+
+const doctor_ports = {
+	format_port_report,
+	read_repository_ports,
+	report_port_seeds,
+	shared_seeds,
+}
+
+export type { RepoPorts as RepositoryPorts }
+export { doctor_ports }