@joshuafolkken/kit 1.872.0

package/scripts/discovery/repo-discovery.ts

@@ -0,0 +1,166 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import path from 'node:path'
+import { repo_map_logic, type DiscoveredRepo, type RepoMap } from './repo-map-logic'
+import { repo_origin } from './repo-origin'
+
+// Finding which repositories sit next to this one, and where.
+//
+// Discovery is automatic by default rather than registered in a config file: on the machine this was
+// written for, every first-party repository is a sibling of every other, so scanning the current
+// repository's parent one level deep produces the same map from whichever of them the command runs
+// in. `JOSH_REPO_PATHS` exists only for the exceptions (joshuafolkken/kit#869).
+
+const GIT_DIRECTORY = '.git'
+const GIT_CONFIG = 'config'
+// A `.git` *file* points at the real git directory (`gitdir: …`), which is how worktrees and
+// submodules are laid out. The pointer is relative to the work tree when it is not absolute.
+const GITDIR_PREFIX = 'gitdir:'
+// A linked worktree's git directory is `<main>/.git/worktrees/<name>`, which holds no `config` of
+// its own — the shared one lives in the common directory that its `commondir` file names, relative
+// to the worktree's git directory. A submodule's git directory has no `commondir` and holds its
+// own `config`, which is why following the pointer alone appeared to work.
+const COMMON_DIRECTORY_FILE = 'commondir'
+const OVERRIDE_ENV_KEY = 'JOSH_REPO_PATHS'
+
+// The directory a git directory's `config` actually lives in: itself, or the common directory a
+// linked worktree points at.
+function resolve_common_directory(git_directory: string): string {
+	const pointer = path.join(git_directory, COMMON_DIRECTORY_FILE)
+	if (!existsSync(pointer)) return git_directory
+
+	try {
+		return path.resolve(git_directory, readFileSync(pointer, 'utf8').trim())
+	} catch {
+		return git_directory
+	}
+}
+
+// Where a `.git` file points. Relative pointers resolve against the work tree holding the file.
+function follow_git_file(repository_path: string, git_file: string): string | undefined {
+	const pointer = readFileSync(git_file, 'utf8').trim()
+	if (!pointer.startsWith(GITDIR_PREFIX)) return undefined
+
+	return path.resolve(repository_path, pointer.slice(GITDIR_PREFIX.length).trim())
+}
+
+// The directory holding the `config` for a work tree: `.git` itself, or — through a `.git` file and
+// then through `commondir` — the shared git directory a linked worktree borrows its remotes from.
+function resolve_git_directory(repository_path: string): string | undefined {
+	const candidate = path.join(repository_path, GIT_DIRECTORY)
+	if (!existsSync(candidate)) return undefined
+
+	try {
+		if (statSync(candidate).isDirectory()) return candidate
+		const linked = follow_git_file(repository_path, candidate)
+
+		return linked === undefined ? undefined : resolve_common_directory(linked)
+	} catch {
+		return undefined
+	}
+}
+
+// The `origin` URL a work tree declares, or nothing when it has no `origin`, no readable config, or
+// is not a work tree at all. Every failure reads as "no remote" so one unreadable sibling cannot
+// fail a command whose contract is to report what it could find.
+function read_origin_url(repository_path: string): string | undefined {
+	const git_directory = resolve_git_directory(repository_path)
+	if (git_directory === undefined) return undefined
+
+	try {
+		return repo_origin.parse_origin_from_config(
+			readFileSync(path.join(git_directory, GIT_CONFIG), 'utf8'),
+		)
+	} catch {
+		return undefined
+	}
+}
+
+// Every immediate child directory of `parent`, in name order. An unreadable parent yields nothing
+// rather than throwing: `josh doctor` reports what it could find, and a permission error on the
+// parent is not a broken install.
+//
+// Sorted because the map keeps the last entry for a repository, and two directories can hold the
+// same one — the second checkout the override variable exists for. Left in `readdir` order, which
+// checkout won would depend on the filesystem, so the same machine could answer differently after a
+// directory was renamed.
+function sibling_directories(parent: string): Array<string> {
+	try {
+		return readdirSync(parent, { withFileTypes: true })
+			.filter((entry) => entry.isDirectory())
+			.map((entry) => path.join(parent, entry.name))
+			.toSorted((left, right) => left.localeCompare(right))
+	} catch {
+		return []
+	}
+}
+
+// Every immediate child of `parent` that holds a git work tree, paired with its `origin`. One level
+// only: a deeper walk would cross into `node_modules` and vendored checkouts, which are not
+// repositories anyone dispatches work to.
+function scan_siblings(parent: string): Array<DiscoveredRepo> {
+	return sibling_directories(parent).map((repository_path) => ({
+		path: repository_path,
+		origin_url: read_origin_url(repository_path),
+	}))
+}
+
+// The owner half of a repository's own `origin`. Read locally rather than asked of `gh`, so the map
+// is built without a network call and without an authenticated CLI.
+function resolve_current_owner(repository_path: string): string | undefined {
+	const origin_url = read_origin_url(repository_path)
+	if (origin_url === undefined) return undefined
+
+	return repo_origin.parse_origin_url(origin_url)?.owner
+}
+
+// The work tree a repository's siblings sit beside: the given path for an ordinary checkout, and the
+// **main** work tree for a linked one. A linked work tree is parked wherever it was created — a lane
+// lives under `.kit-lanes/`, whose only neighbors are that repository's other lanes — so taking the
+// given path's parent as the place to look for siblings finds none of them. The common directory
+// `resolve_git_directory` already follows is `<main>/.git`, so its parent is that main work tree.
+//
+// **Only when the resolved directory is itself a `.git`.** A submodule resolves to
+// `<super>/.git/modules/<path>`, and a bare main repository to `<somewhere>/<name>.git`; neither has
+// a work tree for a parent, so taking one would hand discovery a directory that is not a checkout at
+// all — the very failure this function exists to close, moved somewhere else.
+function main_worktree(repository_path: string): string {
+	const git_directory = resolve_git_directory(repository_path)
+	if (git_directory === undefined) return repository_path
+	if (path.basename(git_directory) !== GIT_DIRECTORY) return repository_path
+
+	return path.dirname(git_directory)
+}
+
+// The map for the repository at `repository_path`. Empty when that repository's own owner cannot be
+// determined: without it there is nothing to compare siblings against, and a map built without the
+// owner restriction is exactly what must never be produced.
+//
+// **Discovery is anchored on the main work tree, resolved here rather than by each caller.** A linked
+// work tree — a lane — is parked among that repository's other lanes, so scanning *its* parent finds
+// none of the siblings; `main_worktree` turns the given path into the main checkout, whose parent
+// holds them. Every command that discovers repositories (`doctor`, `propagate`, `backlog:next`,
+// `epic:next`, `clone:scan`) goes through here, so the anchor lives in one place instead of being
+// re-applied at each call site. For an ordinary checkout, a submodule or a non-repository the
+// resolution is a no-op (`main_worktree` returns the given path), so nothing but a lane is affected.
+function discover_repositories(repository_path: string, environment = process.env): RepoMap {
+	const main = main_worktree(repository_path)
+	const current_owner = resolve_current_owner(main)
+	if (current_owner === undefined) return new Map<string, string>()
+
+	return repo_map_logic.build_repository_map(
+		scan_siblings(path.dirname(main)),
+		current_owner,
+		environment[OVERRIDE_ENV_KEY],
+	)
+}
+
+const repo_discovery = {
+	OVERRIDE_ENV_KEY,
+	main_worktree,
+	read_origin_url,
+	resolve_current_owner,
+	scan_siblings,
+	discover_repositories,
+}
+
+export { repo_discovery }

package/scripts/discovery/repo-map-logic.ts

@@ -0,0 +1,102 @@
+import { repo_origin, type RepoIdentity } from './repo-origin'
+
+// Assembling the `owner/repo` → local path map from what the scan found.
+//
+// The owner restriction lives here, on the single path every entry travels, rather than in the
+// scanner: an override that could re-enter the map behind the filter would be the hole the
+// restriction exists to close. Discovered entries and overrides are both funnelled through
+// `add_entry`, so there is exactly one place that decides what is allowed in
+// (joshuafolkken/kit#869).
+
+// One candidate the scan produced: a directory holding a git work tree, and the `origin` remote it
+// declares. `origin_url` is undefined for a work tree with no `origin` at all.
+interface DiscoveredRepo {
+	path: string
+	origin_url: string | undefined
+}
+
+// `owner/repo` → absolute local path.
+type RepoMap = ReadonlyMap<string, string>
+
+const OVERRIDE_ENTRY_SEPARATOR = ','
+const OVERRIDE_PAIR_SEPARATOR = '='
+const OVERRIDE_PAIR_PARTS = 2
+const KEY_INDEX = 0
+const PATH_INDEX = 1
+
+// Whether an identity belongs to the same owner as the repository the command is running in. This is
+// the first-party test the AI documents define — owner equality, nothing else — and it is not
+// configurable: a sibling directory belonging to another account or organization would otherwise be
+// a repository this tooling could file issues against or push to.
+function is_same_owner(identity: RepoIdentity, current_owner: string): boolean {
+	return identity.owner.toLowerCase() === current_owner.toLowerCase()
+}
+
+// The single gate. Anything reaching the map passes through here, so the owner restriction cannot be
+// bypassed by supplying an entry from a different source.
+function add_entry(
+	target: Map<string, string>,
+	origin_url: string | undefined,
+	repository_path: string,
+	current_owner: string,
+): void {
+	if (origin_url === undefined) return
+	const identity = repo_origin.parse_origin_url(origin_url)
+	if (identity === undefined || !is_same_owner(identity, current_owner)) return
+
+	target.set(repo_origin.format_identity(identity), repository_path)
+}
+
+// One `owner/repo=/absolute/path` pair from the override variable. The key is re-parsed as a remote
+// rather than trusted as written, so an override is held to the same normalization and the same
+// owner restriction as a discovered entry.
+function parse_override_entry(entry: string): DiscoveredRepo | undefined {
+	const parts = entry.split(OVERRIDE_PAIR_SEPARATOR).map((part) => part.trim())
+	if (parts.length !== OVERRIDE_PAIR_PARTS) return undefined
+	const key = parts[KEY_INDEX] ?? ''
+	const repository_path = parts[PATH_INDEX] ?? ''
+	if (repository_path === '') return undefined
+
+	return { path: repository_path, origin_url: `https://${repo_origin.GITHUB_HOST}/${key}` }
+}
+
+// The override variable's entries, in order. Malformed entries are dropped rather than failing the
+// command: `josh doctor` is what a user runs when something is already wrong, and the map it prints
+// is what shows them the override did not take effect.
+function parse_overrides(raw: string | undefined): Array<DiscoveredRepo> {
+	if (raw === undefined) return []
+
+	return raw
+		.split(OVERRIDE_ENTRY_SEPARATOR)
+		.map((entry) => parse_override_entry(entry))
+		.filter((entry): entry is DiscoveredRepo => entry !== undefined)
+}
+
+// The map, from what the scan found plus whatever the override variable adds. Overrides are applied
+// last so an explicit path wins over a discovered one — the escape hatch for a repository that is
+// not a sibling, or one checked out more than once — but they win only *within* the owner
+// restriction, never around it.
+function build_repository_map(
+	discovered: ReadonlyArray<DiscoveredRepo>,
+	current_owner: string,
+	override_value?: string,
+): RepoMap {
+	const result = new Map<string, string>()
+
+	for (const entry of discovered) add_entry(result, entry.origin_url, entry.path, current_owner)
+
+	for (const entry of parse_overrides(override_value)) {
+		add_entry(result, entry.origin_url, entry.path, current_owner)
+	}
+
+	return result
+}
+
+const repo_map_logic = {
+	is_same_owner,
+	parse_overrides,
+	build_repository_map,
+}
+
+export type { DiscoveredRepo, RepoMap }
+export { repo_map_logic }

package/scripts/discovery/repo-origin.ts

@@ -0,0 +1,153 @@
+// Normalizing a git `origin` URL into the `owner/repo` that identifies the repository on GitHub.
+//
+// Kept separate from the map that consumes it (`repo-map-logic.ts`) because the shapes a remote can
+// take are the part with real variety: a single machine's siblings were measured carrying SSH,
+// an SSH host alias, HTTPS with embedded credentials and a trailing slash, and plain HTTPS — all
+// four pointing at the same repository (joshuafolkken/kit#869).
+
+// A repository's identity on GitHub. The `owner` half is what the discovery map filters on, so it is
+// derived here from the remote and never from a directory name.
+interface RepoIdentity {
+	owner: string
+	repo: string
+}
+
+const GITHUB_HOST = 'github.com'
+// An SSH host alias, as written in `~/.ssh/config` (`Host github-work`). Aliases are a local naming
+// concept with no dots, and they exist only in the scp-like SSH form — see `is_github_ssh_host`.
+const SSH_ALIAS_PATTERN = /^github(?:-\w+)*$/u
+const GIT_SUFFIX = '.git'
+const PATH_SEPARATOR = '/'
+const USER_SEPARATOR = '@'
+const HOST_SEPARATOR = ':'
+const OWNER_INDEX = 0
+const REPO_INDEX = 1
+const REPO_PATH_SEGMENTS = 2
+const NOT_FOUND = -1
+const SECTION_PREFIX = '['
+const ORIGIN_SECTION = /^\[remote\s+"origin"\]$/u
+const URL_KEY = 'url'
+
+// Whether a URL's hostname is GitHub. Exact, with no alias spelling accepted: an alias is a name
+// `~/.ssh/config` resolves, so `https://github-internal/owner/repo` is a real host of somebody
+// else's and must not be read as GitHub.
+function is_github_hostname(host: string): boolean {
+	return host.toLowerCase() === GITHUB_HOST
+}
+
+// Whether an SSH remote's host is GitHub: the canonical hostname, or a dotless alias for it as
+// written in `~/.ssh/config` (`Host github-work`). A dotted host is a real hostname and has to match
+// exactly, which is what keeps `github-enterprise.example.com` out.
+function is_github_ssh_host(host: string): boolean {
+	const normalized = host.toLowerCase()
+
+	return is_github_hostname(normalized) || SSH_ALIAS_PATTERN.test(normalized)
+}
+
+function strip_git_suffix(name: string): string {
+	return name.endsWith(GIT_SUFFIX) ? name.slice(0, -GIT_SUFFIX.length) : name
+}
+
+// `owner/repo` from a remote's path. Empty segments are dropped, which absorbs a leading and a
+// trailing slash without a backtracking pattern. Anything that is not exactly two segments is not a
+// repository remote (a gist, a bare host, a nested path) and is rejected rather than guessed.
+function to_identity(repository_path: string): RepoIdentity | undefined {
+	const segments = repository_path.split(PATH_SEPARATOR).filter((segment) => segment !== '')
+	if (segments.length !== REPO_PATH_SEGMENTS) return undefined
+	const owner = segments[OWNER_INDEX] ?? ''
+	const repo = strip_git_suffix(segments[REPO_INDEX] ?? '')
+
+	return repo === '' ? undefined : { owner, repo }
+}
+
+// The `scp`-like SSH form: `git@github.com:owner/repo.git`, and its host-alias variant. Split by
+// hand rather than matched: the pattern for this shape is an optional user part followed by a
+// host — which backtracks super-linearly on a long non-matching remote.
+function parse_scp_like(url: string): RepoIdentity | undefined {
+	const user_end = url.indexOf(USER_SEPARATOR)
+	const authority = user_end === NOT_FOUND ? url : url.slice(user_end + 1)
+	const host_end = authority.indexOf(HOST_SEPARATOR)
+	if (host_end === NOT_FOUND) return undefined
+	if (!is_github_ssh_host(authority.slice(0, host_end))) return undefined
+
+	return to_identity(authority.slice(host_end + 1))
+}
+
+// Any URL form `URL` accepts: `https://user@github.com/owner/repo.git/`, `ssh://git@github.com/…`.
+// Embedded credentials land in `username`/`password` and are dropped with the rest of the authority.
+function parse_url_like(url: string): RepoIdentity | undefined {
+	try {
+		const parsed = new URL(url)
+
+		return is_github_hostname(parsed.hostname) ? to_identity(parsed.pathname) : undefined
+	} catch {
+		return undefined
+	}
+}
+
+// `owner/repo` for a GitHub remote, or nothing for every other remote. Returning nothing is the
+// exclusion the owner restriction depends on: a self-hosted or third-party host never reaches the
+// owner comparison at all (joshuafolkken/kit#869).
+function parse_origin_url(url: string): RepoIdentity | undefined {
+	const trimmed = url.trim()
+	if (trimmed === '') return undefined
+
+	return parse_url_like(trimmed) ?? parse_scp_like(trimmed)
+}
+
+function is_section_header(line: string): boolean {
+	return line.startsWith(SECTION_PREFIX)
+}
+
+// The lines belonging to the `[remote "origin"]` section, in order. A section runs until the next
+// header, so a `url` declared under a different remote is never read as origin's.
+function origin_section_lines(lines: ReadonlyArray<string>): Array<string> {
+	const start = lines.findIndex((line) => ORIGIN_SECTION.test(line))
+	if (start === NOT_FOUND) return []
+	const rest = lines.slice(start + 1)
+	const end = rest.findIndex((line) => is_section_header(line))
+
+	return end === NOT_FOUND ? rest : rest.slice(0, end)
+}
+
+// The value of a `key = value` entry, or nothing when the line declares a different key. Split on
+// the first separator rather than matched, for the reason `parse_scp_like` is split by hand.
+function entry_value(line: string, key: string): string | undefined {
+	const separator = line.indexOf('=')
+	if (separator === NOT_FOUND) return undefined
+	if (line.slice(0, separator).trim() !== key) return undefined
+
+	return line.slice(separator + 1).trim()
+}
+
+// The `url` of the `[remote "origin"]` section of a git config, or nothing when the work tree
+// declares no `origin`. Parsed from the file rather than asked of `git`, because discovery reads one
+// config per sibling directory and spawning a process for each would make `josh doctor` pay a
+// process per unrelated repository sharing the parent directory.
+function parse_origin_from_config(content: string): string | undefined {
+	const lines = content.split('\n').map((line) => line.trim())
+
+	return origin_section_lines(lines)
+		.map((line) => entry_value(line, URL_KEY))
+		.find((url) => url !== undefined)
+}
+
+// The `owner/repo` key a discovery map is keyed by. Lowercased, because GitHub resolves owner and
+// repository names case-insensitively: two remotes spelling the same repository differently are the
+// same repository, and keying by the spelling would put both in the map — where an override, which
+// the caller applies last, would no longer replace the entry it was written to replace.
+function format_identity(identity: RepoIdentity): string {
+	return `${identity.owner}${PATH_SEPARATOR}${identity.repo}`.toLowerCase()
+}
+
+const repo_origin = {
+	GITHUB_HOST,
+	is_github_hostname,
+	is_github_ssh_host,
+	parse_origin_from_config,
+	parse_origin_url,
+	format_identity,
+}
+
+export type { RepoIdentity }
+export { repo_origin }

package/scripts/discovery/repo-party-cli.ts

@@ -0,0 +1,69 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { repo_party, type Party } from './repo-party'
+
+// `josh repo:party [<owner/repo>]` — say whether a repository is first-party or third-party
+// (joshuafolkken/kit#2122). A command rather than a paragraph, for the reason `josh latest:scope` is
+// one: a rule an agent applies from memory is a rule an agent can talk itself out of, and this one is
+// argued against at exactly the moment a workflow wants to write to another repository.
+//
+// The word alone on stdout so `$(pnpm josh repo:party o/r)` reads it, and the two owners it compared
+// on stderr so a person sees why without a shell having to parse around it — the split
+// `josh latest:scope` prints in.
+
+const ARGV_OFFSET = 2
+const USAGE = 'Usage: josh repo:party [<owner/repo>]'
+const FAILURE_EXIT_CODE = 1
+const FLAG_PREFIX = '-'
+const NONE_ARGUMENT = 0
+const ONE_ARGUMENT = 1
+const UNREADABLE = '(unreadable)'
+
+interface Decision {
+	party: Party
+	detail: string
+}
+
+function owner_label(owner: string | undefined): string {
+	return owner ?? UNREADABLE
+}
+
+// No argument targets the session's own repository, so both owners are the session's and the answer
+// is `first-party` unless the session's remote cannot be read. The stderr line names the two owners
+// the classification actually compared, whichever arm was taken.
+function decide(owner_repo: string | undefined): Decision {
+	const session_owner = repo_party.current_owner()
+	const target = owner_repo === undefined ? session_owner : repo_party.target_owner(owner_repo)
+
+	return {
+		party: repo_party.classify(session_owner, target),
+		detail: `session owner: ${owner_label(session_owner)} · target owner: ${owner_label(target)}`,
+	}
+}
+
+function run(argv: ReadonlyArray<string>): number {
+	const positional = argv.filter((argument) => !argument.startsWith(FLAG_PREFIX))
+
+	if (positional.length !== NONE_ARGUMENT && positional.length !== ONE_ARGUMENT) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const decision = decide(positional[0])
+
+	console.info(decision.party)
+	console.error(decision.detail)
+
+	return 0
+}
+
+function main(argv: ReadonlyArray<string>): void {
+	process.exitCode = run(argv)
+}
+
+const repo_party_cli = { USAGE, decide, main, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(ARGV_OFFSET))
+
+export { repo_party_cli }

package/scripts/discovery/repo-party.ts

@@ -0,0 +1,46 @@
+import { repo_discovery } from './repo-discovery'
+import { repo_origin } from './repo-origin'
+
+// **First-party vs third-party, computed rather than judged** (joshuafolkken/kit#2122). `CLAUDE.md`
+// and `upstream-interrupt.md` both declared the test mechanical — owner equality between the target
+// repository and the session's — yet nothing computed it: three prose spots restated the manual
+// `gh api … --jq .owner.login`, and whether an owner had actually been read was left to trust. This is
+// the computation those documents describe, so the rule that refuses a third-party write and the
+// `josh repo:party` oracle read one definition rather than two.
+//
+// **The owner comparison is case-insensitive**, because GitHub resolves owner names that way — the
+// same reason `repo-origin.ts` lowercases the discovery key. Two spellings of one owner are one owner.
+
+type Party = 'first-party' | 'third-party' | 'unknown'
+
+const FIRST_PARTY: Party = 'first-party'
+const THIRD_PARTY: Party = 'third-party'
+const UNKNOWN: Party = 'unknown'
+
+// `unknown` is not `third-party`. An owner that cannot be read — no `origin`, an unreadable config —
+// is a "cannot decide", and reading it as third-party would refuse first-party writes whenever the
+// session's own remote was momentarily unreadable. The caller decides what a `unknown` licenses;
+// the deny rule treats it as "not proven third-party" and stays silent.
+function classify(session_owner: string | undefined, target: string | undefined): Party {
+	if (session_owner === undefined || target === undefined) return UNKNOWN
+
+	return session_owner.toLowerCase() === target.toLowerCase() ? FIRST_PARTY : THIRD_PARTY
+}
+
+// The owner half of a `owner/repo` argument, parsed through the remote-URL reader so a `.git` suffix
+// and a malformed form (one segment, three segments) are handled by the one place that already knows
+// them rather than by a second split here.
+function target_owner(owner_repo: string): string | undefined {
+	return repo_origin.parse_origin_url(`https://${repo_origin.GITHUB_HOST}/${owner_repo}`)?.owner
+}
+
+// The owner of the repository the session runs in, read locally from its `origin` — no network call
+// and no authenticated CLI, so the guard that consults it stays synchronous.
+function current_owner(repository_path: string = process.cwd()): string | undefined {
+	return repo_discovery.resolve_current_owner(repository_path)
+}
+
+const repo_party = { FIRST_PARTY, THIRD_PARTY, UNKNOWN, classify, current_owner, target_owner }
+
+export type { Party }
+export { repo_party }