jackherd 0.0.1 → 1.0.0

package/src/check/public-content.ts

@@ -0,0 +1,216 @@
+import { escapeRegExp } from '../plan-format/markdown'
+import { CHECK_STATUS, type CheckResult } from './result'
+
+export const TERM_KIND = {
+  neighbourRepository: 'neighbour repository',
+  gitOrganisation: 'git organisation',
+  ticketKey: 'ticket key',
+  projectName: 'project name',
+  packageScope: 'package scope',
+  domain: 'domain',
+  localTerm: 'local term',
+} as const
+
+/** What a term names; a hit reports this, never the term. */
+export type TermKind = (typeof TERM_KIND)[keyof typeof TERM_KIND]
+
+/** A word that must not reach published files. It lives for one run: never written, never printed. */
+export type Term = { kind: TermKind; text: string }
+
+export type Neighbour = {
+  /** The directory name of a repository beside this one or in a work directory. */
+  name: string
+  /** Remote URLs as `git remote -v` lists them. */
+  remotes: string[]
+  /** Local and remote branch names. */
+  branches: string[]
+}
+
+/** What the repository and its neighbours tell about the people and projects the published files must not name. */
+export type PublicContentFacts = {
+  neighbours: Neighbour[]
+  /** Folder names of the project's apps and services. */
+  apps: string[]
+  /** Scopes of the project's own package names (`@scope`). */
+  scopes: string[]
+  /** Scopes of the published packages themselves; their names are what they are published under. */
+  ownScopes: string[]
+  /** The text of the project's env example files. */
+  envExamples: string[]
+  /** Terms from the user's local file outside every repository. */
+  localTerms: string[]
+}
+
+export type AddedLine = { path: string; line: number; text: string }
+
+/** A hit names where and what kind of name, never the name itself. */
+export type PublicLeak = { path: string; line: number; kind: TermKind }
+
+/** Below this length a name is too likely to be an ordinary word or an abbreviation. */
+const MIN_TERM_LENGTH = 4
+
+/** Repository and folder names too generic to tell anyone anything. */
+const GENERIC_NAMES = new Set([
+  'agent',
+  'agents',
+  'apps',
+  'backend',
+  'config',
+  'configs',
+  'demo',
+  'docs',
+  'dotfiles',
+  'example',
+  'examples',
+  'frontend',
+  'infra',
+  'infrastructure',
+  'master',
+  'main',
+  'notes',
+  'packages',
+  'platform',
+  'playground',
+  'sandbox',
+  'scripts',
+  'server',
+  'services',
+  'shared',
+  'skills',
+  'test',
+  'tests',
+  'tools',
+  'website',
+  'workspace',
+])
+
+/** Hosts every project names; a domain is the project's only when it is none of these. */
+const PUBLIC_HOSTS = new Set(['localhost', 'example.com', 'example.org', 'example.net', 'github.com', 'gitlab.com'])
+
+const REMOTE_PATH = /(?:[:/])([^/:\s]+)\/([^/\s]+?)(?:\.git)?\/?$/
+
+const TICKET_KEY = /(?:^|[/_-])([A-Z][A-Z0-9]{1,9})-\d+/
+
+const HOST = /\b(?:[a-z0-9-]+\.)+[a-z]{2,}\b/gi
+
+const isUsefulName = (name: string): boolean => name.length >= MIN_TERM_LENGTH && !GENERIC_NAMES.has(name.toLowerCase())
+
+const remoteNames = (remote: string): Term[] => {
+  const match = REMOTE_PATH.exec(remote.trim())
+  if (!match) return []
+  return [
+    { kind: TERM_KIND.gitOrganisation, text: match[1] },
+    { kind: TERM_KIND.neighbourRepository, text: match[2] },
+  ]
+}
+
+const ticketKeys = (branches: readonly string[]): Term[] =>
+  branches.flatMap((branch) => {
+    const match = TICKET_KEY.exec(branch)
+    return match ? [{ kind: TERM_KIND.ticketKey, text: match[1] }] : []
+  })
+
+const neighbourTerms = (neighbour: Neighbour): Term[] => [
+  { kind: TERM_KIND.neighbourRepository, text: neighbour.name },
+  ...neighbour.remotes.flatMap(remoteNames),
+  ...ticketKeys(neighbour.branches),
+]
+
+/** The last two labels of a host: `stage.shop.example.io` → `example.io`. */
+const registrableDomain = (host: string): string => host.toLowerCase().split('.').slice(-2).join('.')
+
+const domainTerms = (envExamples: readonly string[]): Term[] =>
+  envExamples
+    .flatMap((text) => text.match(HOST) ?? [])
+    .map(registrableDomain)
+    .filter((domain) => !PUBLIC_HOSTS.has(domain))
+    .map((text) => ({ kind: TERM_KIND.domain, text }))
+
+const scopeName = (scope: string): string => scope.replace(/^@/, '')
+
+const projectTerms = (facts: PublicContentFacts): Term[] => {
+  const own = new Set(facts.ownScopes.map(scopeName))
+  return [
+    ...facts.apps.map((text): Term => ({ kind: TERM_KIND.projectName, text })),
+    ...facts.scopes
+      .map(scopeName)
+      .filter((scope) => !own.has(scope))
+      .map((text): Term => ({ kind: TERM_KIND.packageScope, text })),
+    ...domainTerms(facts.envExamples),
+  ]
+}
+
+/** A ticket key is kept short (`AB`): it only ever matches together with its number. */
+const isKept = (term: Term, own: ReadonlySet<string>): boolean => {
+  if (own.has(term.text.toLowerCase())) return false
+  if (term.kind === TERM_KIND.ticketKey || term.kind === TERM_KIND.localTerm) return term.text.length > 0
+  return isUsefulName(term.text)
+}
+
+const dedupe = (terms: readonly Term[]): Term[] => {
+  const seen = new Set<string>()
+  return terms.filter((term) => {
+    const key = term.text.toLowerCase()
+    if (seen.has(key)) return false
+    seen.add(key)
+    return true
+  })
+}
+
+/** Every term the facts yield, short and generic names and the published packages' own scopes left out. */
+export const deriveTerms = (facts: PublicContentFacts): Term[] => {
+  const own = new Set(facts.ownScopes.map((scope) => scopeName(scope).toLowerCase()))
+  const terms: Term[] = [
+    ...facts.neighbours.flatMap(neighbourTerms),
+    ...projectTerms(facts),
+    ...facts.localTerms.map((text): Term => ({ kind: TERM_KIND.localTerm, text: text.trim() })),
+  ]
+  return dedupe(terms.filter((term) => isKept(term, own)))
+}
+
+/** Matches the term as a whole word in any case; letters and digits of any script bound a word. */
+const termPattern = (term: Term): RegExp =>
+  term.kind === TERM_KIND.ticketKey
+    ? new RegExp(`(?<![\\p{L}\\p{N}])${escapeRegExp(term.text)}-\\d+`, 'u')
+    : new RegExp(`(?<![\\p{L}\\p{N}])${escapeRegExp(term.text)}(?![\\p{L}\\p{N}])`, 'iu')
+
+/** Drops the terms the published files already use: those are the kit's own words, whatever else they name. */
+export const withoutVocabulary = (terms: readonly Term[], vocabulary: string): Term[] =>
+  terms.filter((term) => !termPattern(term).test(vocabulary))
+
+const HUNK = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/
+
+/** The added lines of a `git diff --unified=0`, with their line numbers in the new file. */
+export const addedLines = (diff: string): AddedLine[] => {
+  const lines: AddedLine[] = []
+  let path = ''
+  let next = 0
+  for (const line of diff.split('\n')) {
+    if (line.startsWith('+++ ')) path = line.replace(/^\+\+\+ (b\/)?/, '')
+    else if (HUNK.test(line)) next = Number(HUNK.exec(line)?.[1])
+    else if (line.startsWith('+')) lines.push({ path, line: next++, text: line.slice(1) })
+  }
+  return lines
+}
+
+/** Every added line against every term; a hit carries the term's kind, not the term. */
+export const findPublicLeaks = (lines: readonly AddedLine[], terms: readonly Term[]): PublicLeak[] => {
+  const patterns = terms.map((term) => ({ kind: term.kind, pattern: termPattern(term) }))
+  return lines.flatMap(({ path, line, text }) =>
+    patterns.filter(({ pattern }) => pattern.test(text)).map(({ kind }) => ({ path, line, kind })),
+  )
+}
+
+/** The report line of the scan: where each hit is and what kind of name it is, never the name. */
+export const publicContentResult = (
+  leaks: readonly PublicLeak[],
+  scope: { files: number; terms: number },
+  durationMs: number,
+): CheckResult => ({
+  name: 'Public content',
+  command: `${scope.files} published files changed, ${scope.terms} names of neighbouring projects and of this one`,
+  status: leaks.length === 0 ? CHECK_STATUS.pass : CHECK_STATUS.fail,
+  detail:
+    leaks.map(({ path, line, kind }) => `${path}:${line} names a ${kind}`).join('\n') || 'no added line names them',
+  durationMs,
+})

package/src/check/report.ts

@@ -0,0 +1,55 @@
+import { type ChangedFile, STATUS_COMMAND } from './changes'
+import type { CheckPlan } from './plan'
+import { CHECK_STATUS, type CheckResult, SKIP_SLOW_FLAG } from './result'
+
+const STATUS_ICON = { pass: '✅', fail: '❌', warn: '⚠️ ', skipped: '⏭️ ' } as const
+
+export const artifactResult = (artifacts: readonly string[]): CheckResult => ({
+  name: 'Staged build artifacts',
+  command: STATUS_COMMAND.join(' '),
+  status: artifacts.length === 0 ? CHECK_STATUS.pass : CHECK_STATUS.fail,
+  detail: artifacts.join('\n') || 'none staged',
+  durationMs: 0,
+})
+
+export const skippedSlowResult = (): CheckResult => ({
+  name: 'Types & tests',
+  command: SKIP_SLOW_FLAG,
+  status: CHECK_STATUS.skipped,
+  detail: 'skipped on request',
+  durationMs: 0,
+})
+
+export const formatPlanHeader = (files: readonly ChangedFile[], plan: CheckPlan): string[] => [
+  `Changed files (${files.length}, ${files.filter((file) => file.staged).length} staged):`,
+  ...files.map((file) => `   ${file.staged ? 'S' : ' '} ${file.path}`),
+  '',
+  `Package roots: ${plan.roots.join(', ') || 'none'}`,
+  `Reviewers: ${plan.reviewers.join(', ') || 'none'}`,
+  ...(plan.generated.length > 0
+    ? [
+        'Generator-owned files (must come from the generator, not from an editor):',
+        ...plan.generated.map(({ path, generator }) => `   ${path}  →  ${generator}`),
+      ]
+    : []),
+  '',
+]
+
+export const formatResults = (results: readonly CheckResult[]): string[] =>
+  results.flatMap((result) => [
+    `${STATUS_ICON[result.status]} ${result.name}  (${result.command}, ${result.durationMs}ms)`,
+    ...(result.status !== CHECK_STATUS.pass && result.detail
+      ? result.detail.split('\n').map((line) => `     ${line}`)
+      : []),
+  ])
+
+const warnings = (count: number): string => (count > 0 ? `${count} ${count === 1 ? 'warning' : 'warnings'}, ` : '')
+
+export const summarize = (results: readonly CheckResult[]): { line: string; failed: number } => {
+  const count = (status: CheckResult['status']) => results.filter((result) => result.status === status).length
+  const failed = count(CHECK_STATUS.fail)
+  return {
+    failed,
+    line: `${failed === 0 ? '✅' : '❌'} ${count(CHECK_STATUS.pass)} passed, ${failed} failed, ${warnings(count(CHECK_STATUS.warn))}${count(CHECK_STATUS.skipped)} skipped`,
+  }
+}

package/src/check/result.ts

@@ -0,0 +1,42 @@
+import type { PlannedCheck } from './plan'
+import { CHECK_KIND } from './plan'
+
+/** `warn` reports a finding without failing the run. */
+export const CHECK_STATUS = { pass: 'pass', fail: 'fail', warn: 'warn', skipped: 'skipped' } as const
+
+export type CheckStatus = (typeof CHECK_STATUS)[keyof typeof CHECK_STATUS]
+
+export type CheckResult = {
+  name: string
+  command: string
+  status: CheckStatus
+  detail: string
+  durationMs: number
+}
+
+export type ProcessResult = { ok: boolean; output: string }
+
+export const SKIP_SLOW_FLAG = '--skip-slow'
+
+/**
+ * Bun reports "there was nothing to run" in two shapes: a package whose files hold no test cases
+ * summarises as `0 tests`, one with no matching files exits non-zero with `0 test files matching`.
+ * Both are an absent suite, not a failing one.
+ */
+export const reportsNoTests = (output: string): boolean => /^0 tests|no tests found|0 test files/im.test(output)
+
+export const lastLines = (output: string, count: number): string =>
+  output.split('\n').filter(Boolean).slice(-count).join('\n')
+
+/** How a finished process reads for its check: an absent test suite is skipped, not failed. */
+export const outcomeOf = (
+  check: PlannedCheck,
+  { ok, output }: ProcessResult,
+): Pick<CheckResult, 'status' | 'detail'> => {
+  if (check.kind === CHECK_KIND.tests && reportsNoTests(output)) {
+    return { status: CHECK_STATUS.skipped, detail: 'no tests in this directory' }
+  }
+  return ok
+    ? { status: CHECK_STATUS.pass, detail: lastLines(output, check.kind === CHECK_KIND.tests ? 3 : 2) }
+    : { status: CHECK_STATUS.fail, detail: lastLines(output, 20) }
+}

package/src/check/roots.ts

@@ -0,0 +1,36 @@
+import { dirname } from 'node:path'
+
+/**
+ * The nearest ancestor holding a `package.json`. Tests and `tsc` run from there and nowhere else:
+ * Bun resolves `tsconfig.json` from the working directory, so descending below a package root
+ * silently compiles `.tsx` against the wrong JSX runtime.
+ */
+export const packageRootOf = (path: string, hasPackageJson: (dir: string) => boolean): string | null => {
+  let dir = dirname(path)
+  while (dir !== '.' && dir !== '/' && dir !== '') {
+    if (hasPackageJson(dir)) return dir
+    dir = dirname(dir)
+  }
+  return hasPackageJson('.') ? '.' : null
+}
+
+export const packageRootsFor = (paths: readonly string[], hasPackageJson: (dir: string) => boolean): string[] => [
+  ...new Set(paths.map((path) => packageRootOf(path, hasPackageJson)).filter((root): root is string => root !== null)),
+]
+
+/**
+ * Directories with test files that belong to no package root, which would otherwise be tested by
+ * nobody. The workspace root is excluded: a test run from there walks the whole monorepo.
+ */
+export const looseDirectories = (
+  paths: readonly string[],
+  roots: readonly string[],
+  hasTests: (dir: string) => boolean,
+): string[] => [
+  ...new Set(
+    paths
+      .filter((path) => !roots.some((root) => path.startsWith(`${root}/`)))
+      .map((path) => dirname(path))
+      .filter((dir) => dir !== '.' && hasTests(dir)),
+  ),
+]

package/src/check/routing.ts

@@ -0,0 +1,22 @@
+import { matchesAnyGlob } from './glob'
+import type { ProjectCheck, PublicContentConfig, ReviewerRoute } from './schema'
+
+/** Reviewers whose route matches at least one changed path, in route order. */
+export const reviewersFor = (paths: readonly string[], routes: readonly ReviewerRoute[]): string[] =>
+  routes.filter((route) => paths.some((path) => matchesAnyGlob(path, route.globs))).map((route) => route.reviewer)
+
+/** Whether a published package ships the path, by `check.publicContent`; never without it. */
+export const isPublicPath = (path: string, config: PublicContentConfig | undefined): boolean =>
+  config !== undefined && matchesAnyGlob(path, config.globs) && !matchesAnyGlob(path, config.exclude)
+
+/** The changed paths a published package ships. */
+export const publicPathsOf = (paths: readonly string[], config: PublicContentConfig | undefined): string[] =>
+  paths.filter((path) => isPublicPath(path, config))
+
+/** The public-content reviewer when a change touches a published file. */
+export const publicContentReviewers = (paths: readonly string[], config: PublicContentConfig | undefined): string[] =>
+  config && publicPathsOf(paths, config).length > 0 ? [config.reviewer] : []
+
+/** Project checks a change triggers: those without globs always, those with globs when a path matches. */
+export const projectChecksFor = (paths: readonly string[], checks: readonly ProjectCheck[]): ProjectCheck[] =>
+  checks.filter(({ globs }) => !globs || paths.some((path) => matchesAnyGlob(path, globs)))

package/src/check/schema.ts

@@ -0,0 +1,83 @@
+import { z } from 'zod'
+import { BUN_COMMANDS } from '../config/detect'
+import { tokenize } from './command-line'
+
+const nonEmpty = z.string().min(1)
+
+const isTokenizable = (command: string): boolean => {
+  try {
+    tokenize(command)
+    return true
+  } catch {
+    return false
+  }
+}
+
+const command = nonEmpty.refine(isTokenizable, 'Unterminated quote in command')
+
+/** Supports `*`, `**` and `?`; braces and brackets would silently match nothing, so they are refused. */
+const glob = nonEmpty.refine((value) => !/[{}[\]]/.test(value), 'Braces and brackets are not supported in globs')
+
+const globs = z.array(glob).min(1)
+
+/** Staged output that belongs to a build, never to a commit. */
+export const DEFAULT_BUILD_ARTIFACT_GLOBS = [
+  '**/tsup.config.bundled_*',
+  '**/dist/**',
+  '**/.turbo/**',
+  '**/node_modules/**',
+  '**/*.tsbuildinfo',
+] as const
+
+const reviewerRoute = z.strictObject({
+  reviewer: nonEmpty,
+  globs,
+  why: nonEmpty,
+})
+
+const projectCheck = z.strictObject({
+  name: nonEmpty,
+  command,
+  /** Without globs the check runs on every change; with them, only when a changed path matches. */
+  globs: globs.optional(),
+})
+
+const generatorOwned = z.strictObject({
+  glob,
+  generator: nonEmpty,
+})
+
+/** Files a published package ships, so they never name the projects, people or teams around it. */
+const publicContent = z.strictObject({
+  /** The published files: a change here gets the reviewer and the scan for names of neighbouring projects. */
+  globs,
+  /** Files among them that never ship, such as tests. */
+  exclude: z.array(glob).default([]),
+  /** The agent that judges such a change; a global install names it with its prefix. */
+  reviewer: nonEmpty.default('public-content'),
+})
+
+/**
+ * The `check` block of `.jackherd/config.json`. Test and type commands come from the top-level
+ * `commands` block; this block holds what only the check runner reads.
+ */
+export const checkConfigSchema = z.strictObject({
+  /**
+   * Run once over the changed files, which are appended as arguments. Separate from `commands.lint`,
+   * which lints the whole project.
+   */
+  lintFilesCommand: command.default(BUN_COMMANDS.lintFiles),
+  /** Project checks, run alongside lint; add repository-specific scripts here. */
+  checks: z.array(projectCheck).default([]),
+  generatorOwned: z.array(generatorOwned).default([]),
+  buildArtifacts: z.array(glob).default([...DEFAULT_BUILD_ARTIFACT_GLOBS]),
+  reviewerRoutes: z.array(reviewerRoute).default([]),
+  publicContent: publicContent.optional(),
+  /** Also run tests in directories that hold test files but belong to no package. */
+  looseTests: z.boolean().default(false),
+})
+
+export type CheckConfig = z.infer<typeof checkConfigSchema>
+export type ReviewerRoute = CheckConfig['reviewerRoutes'][number]
+export type ProjectCheck = CheckConfig['checks'][number]
+export type PublicContentConfig = NonNullable<CheckConfig['publicContent']>

package/src/check/settings.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod'
+import { jackherdConfigSchema } from '../config'
+import { type RepositoryFacts, withDetected } from '../config/detect'
+import { PROJECT_CONFIG_PATH } from '../config/location'
+import type { PlanLanguage } from '../vocabulary'
+import type { PackageCommands } from './plan'
+import { type CheckConfig, checkConfigSchema } from './schema'
+
+export const CONFIG_PATH = PROJECT_CONFIG_PATH
+
+/** `notes` name the values the repository did not decide (see `withDetected`). */
+export type CheckSettings = {
+  commands: PackageCommands
+  check: CheckConfig
+  planDirectory: string
+  planLanguage: PlanLanguage
+  /** The branch on the remote whose plans count as merged. */
+  baseBranch: string
+  notes: string[]
+}
+
+const commandsSchema = jackherdConfigSchema.shape.commands
+const planDirectorySchema = jackherdConfigSchema.shape.planDirectory
+const planLanguageSchema = jackherdConfigSchema.shape.planLanguage
+const baseBranchSchema = jackherdConfigSchema.shape.baseBranch
+
+/**
+ * The check runner's view of `.jackherd/config.json`: the shared `commands` block, `planDirectory`, `planLanguage` and `baseBranch` plus its own
+ * `check` block, with what the file leaves out detected from the repository. The rest of the file is
+ * validated by the commands that use it, not here.
+ */
+export const parseCheckSettings = (raw: unknown, facts: RepositoryFacts): CheckSettings => {
+  const detected = withDetected(z.record(z.string(), z.unknown()).parse(raw), facts)
+  const object = z.record(z.string(), z.unknown()).parse(detected.raw)
+  const { test, typecheck } = commandsSchema.parse(object.commands)
+  return {
+    commands: { test, typecheck },
+    check: checkConfigSchema.parse(object.check ?? {}),
+    planDirectory: planDirectorySchema.parse(object.planDirectory),
+    planLanguage: planLanguageSchema.parse(object.planLanguage),
+    baseBranch: baseBranchSchema.parse(object.baseBranch),
+    notes: detected.notes,
+  }
+}

package/src/claude/paths.ts

@@ -0,0 +1,14 @@
+/** Where Claude Code itself reads skills, agents, rules, hooks and session logs: the one place that names them. */
+export const CLAUDE_DIRECTORY = '.claude'
+export const SETTINGS_FILE = 'settings.json'
+export const LOCAL_SETTINGS_FILE = 'settings.local.json'
+
+export const SKILLS_DIRECTORY = 'skills'
+export const AGENTS_DIRECTORY = 'agents'
+export const RULES_DIRECTORY = 'rules'
+export const HANDOVER_DIRECTORY = 'handover'
+export const WORKTREES_DIRECTORY = 'worktrees'
+export const SESSION_LOGS_DIRECTORY = 'projects'
+
+/** `.claude/<directory>` as a path in a project and in a text that names it. */
+export const claudePath = (...segments: string[]): string => [CLAUDE_DIRECTORY, ...segments].join('/')

package/src/cli.ts

@@ -0,0 +1,46 @@
+#!/usr/bin/env bun
+import { pathToFileURL } from 'node:url'
+import { CLI_NAME } from './version/release'
+
+export type CommandModule = { run: (args: string[]) => Promise<number> | number }
+
+export type CommandTable = Record<string, () => Promise<CommandModule>>
+
+export type Resolution =
+  | { kind: 'run'; name: string; args: string[] }
+  | { kind: 'usage'; exitCode: number; message: string }
+
+/** One line per command; each entry lazily imports the module that exports its `run`. */
+export const COMMANDS: CommandTable = {
+  check: () => import('./check/command'),
+  config: () => import('./config/command'),
+  context: () => import('./context/command'),
+  init: () => import('./sync/init-command'),
+  plans: () => import('./plans/command'),
+  sync: () => import('./sync/command'),
+  update: () => import('./update/command'),
+  watch: () => import('./watch/command'),
+}
+
+export const resolveCommand = (argv: string[], table: CommandTable): Resolution => {
+  const [name, ...args] = argv
+  const names = Object.keys(table)
+  const usage = `Usage: ${CLI_NAME} <command> [args]\nCommands: ${names.length > 0 ? names.join(', ') : '(none yet)'}`
+  if (!name || name === '--help' || name === '-h') return { kind: 'usage', exitCode: name ? 0 : 1, message: usage }
+  if (!names.includes(name)) return { kind: 'usage', exitCode: 1, message: `Unknown command: ${name}\n${usage}` }
+  return { kind: 'run', name, args }
+}
+
+export const main = async (argv: string[], table: CommandTable = COMMANDS): Promise<number> => {
+  const resolution = resolveCommand(argv, table)
+  if (resolution.kind === 'usage') {
+    console.log(resolution.message)
+    return resolution.exitCode
+  }
+  const command = await table[resolution.name]()
+  return command.run(resolution.args)
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  process.exitCode = await main(process.argv.slice(2))
+}

package/src/config/command.ts

@@ -0,0 +1,45 @@
+import { homedir } from 'node:os'
+import { mainCheckout, worktreeRoot } from '../plans/git'
+import { CLI_NAME } from '../version/release'
+import { readResolvedConfig } from './read-config'
+import { formatRepositoryValues, isRepositoryValue, REPOSITORY_VALUE, repositoryValuesOf } from './repository-values'
+
+const USAGE = `Usage: ${CLI_NAME} config [${Object.values(REPOSITORY_VALUE).join(' | ')}]`
+
+const USAGE_EXIT = 2
+
+export type ConfigOutput = { log: (line: string) => void; error: (line: string) => void }
+
+/**
+ * Prints the values this repository decides, as the config sets them or detection finds them: all of them, or
+ * the one `key` names. Notes about values the repository did not decide go to `error`, so a key's output stays
+ * the bare value.
+ */
+export const printRepositoryValues = (args: string[], roots: string[], home: string, output: ConfigOutput): number => {
+  const [key, extra] = args
+  if (extra !== undefined) {
+    output.error(USAGE)
+    return USAGE_EXIT
+  }
+  if (key !== undefined && !isRepositoryValue(key)) {
+    output.error(`Unknown key: ${key}\n${USAGE}`)
+    return USAGE_EXIT
+  }
+  const { config, notes } = readResolvedConfig(roots, home)
+  for (const note of notes) output.error(note)
+  const values = repositoryValuesOf(config)
+  const lines = key === undefined ? formatRepositoryValues(values) : [values[key]]
+  for (const line of lines) output.log(line)
+  return 0
+}
+
+export const run = (args: string[]): number => {
+  const output = { log: (line: string) => console.log(line), error: (line: string) => console.error(line) }
+  try {
+    const cwd = process.cwd()
+    return printRepositoryValues(args, [worktreeRoot(cwd), mainCheckout(cwd)], homedir(), output)
+  } catch (error) {
+    output.error(`${CLI_NAME} config failed: ${error instanceof Error ? error.message : String(error)}`)
+    return 1
+  }
+}