@hearthkit/cli 0.1.0

package/src/parse-cli-invocation.ts

@@ -0,0 +1,365 @@
+import { isAbsolute, resolve } from 'node:path'
+import { postgresConnectionStringSchema, projectDatabaseNameSchema } from '@hearthkit/db'
+import {
+  cliCommandPathSchema,
+  defaultMigrationsFolderPath,
+  defaultPaymentsCatalogPath,
+  type CliCommandInvocation,
+  type CliCommandPath,
+  type CliFailure,
+} from './cli-contract.ts'
+import {
+  cliUsageInvalidFailure,
+  databaseUrlInvalidFailure,
+  databaseUrlMissingFailure,
+} from './cli-failure-results.ts'
+import type { CliRuntimeContext } from './cli-runtime-context.ts'
+import { buildDefaultBackupFilePath } from './default-backup-file-path.ts'
+import { readEnvironmentVariableValue } from './read-environment-variable-value.ts'
+import { resolveAdminDatabaseUrl } from './resolve-admin-database-url.ts'
+
+/** The project-scoped connection db migrate falls back to; never the admin connection, per the db contract. */
+const projectDatabaseUrlEnvVariableName = 'DATABASE_URL'
+
+/** Flags that take the next word as their value; every other double-dash word is either a boolean flag or unknown. */
+const valueFlagNames = [
+  '--admin-database-url',
+  '--database-url',
+  '--migrations-folder',
+  '--backup-file',
+  '--catalog',
+] as const
+
+/** Flags that stand alone; giving one a value is a usage failure rather than a silently ignored word. */
+const booleanFlagNames = ['--json'] as const
+
+/** Which flags each command accepts, so --json on db create is rejected instead of quietly doing nothing. */
+const allowedFlagNamesByCommandPath: Record<CliCommandPath, readonly string[]> = {
+  'db create': ['--admin-database-url'],
+  'db drop': ['--admin-database-url'],
+  'db migrate': ['--database-url', '--migrations-folder'],
+  'db backup': ['--admin-database-url', '--backup-file'],
+  'db restore': ['--admin-database-url'],
+  dev: [],
+  'dev infra up': [],
+  'dev infra down': [],
+  doctor: ['--json'],
+  'payments sync': ['--catalog'],
+}
+
+/** How many words follow the command itself; checked before any word is handed to a schema. */
+const commandArgumentCountByPath: Record<CliCommandPath, number> = {
+  'db create': 1,
+  'db drop': 1,
+  'db migrate': 0,
+  'db backup': 1,
+  'db restore': 2,
+  dev: 0,
+  'dev infra up': 0,
+  'dev infra down': 0,
+  doctor: 0,
+  'payments sync': 0,
+}
+
+/** A parsed invocation ready to run, or the failure to report; parsing never throws and never runs a command. */
+export type CliInvocationParse =
+  | { kind: 'cli-invocation-parsed'; invocation: CliCommandInvocation }
+  | { kind: 'cli-invocation-rejected'; failure: CliFailure }
+
+/** argv split into command words and flags before any command is known; unknown flags are rejected here. */
+type CliArgumentSplit =
+  | {
+      kind: 'cli-arguments-split'
+      commandWords: string[]
+      flagValues: Map<string, string>
+      presentBooleanFlagNames: Set<string>
+      givenFlagNames: Set<string>
+    }
+  | { kind: 'cli-arguments-rejected'; failure: CliFailure }
+
+/**
+ * Turns argv plus the environment into one runnable invocation. Word-shaped mistakes are usage
+ * failures (exit 2); a well-formed command whose connection URL does not hold up is an operational
+ * failure (exit 1), which is why URL resolution happens here rather than inside a command handler.
+ */
+export function parseCliInvocation(options: {
+  argv: readonly string[]
+  context: CliRuntimeContext
+}): CliInvocationParse {
+  const split = splitCliArguments(options.argv)
+  if (split.kind === 'cli-arguments-rejected') {
+    return { kind: 'cli-invocation-rejected', failure: split.failure }
+  }
+
+  const match = matchCommandPath(split.commandWords)
+  if (match.kind === 'command-path-unknown') {
+    return rejectedInvocation(
+      cliUsageInvalidFailure(
+        `unknown command ${JSON.stringify(split.commandWords.join(' '))}; expected one of ${cliCommandPathSchema.options.join(', ')}`,
+      ),
+    )
+  }
+  if (match.kind === 'command-argument-count-wrong') {
+    return rejectedInvocation(
+      cliUsageInvalidFailure(
+        `${match.commandPath} takes ${commandArgumentCountByPath[match.commandPath]} argument(s), ${match.commandArguments.length} given`,
+      ),
+    )
+  }
+
+  const unknownFlagName = [...split.givenFlagNames].find(
+    (flagName) => !allowedFlagNamesByCommandPath[match.commandPath].includes(flagName),
+  )
+  if (unknownFlagName !== undefined) {
+    return rejectedInvocation(
+      cliUsageInvalidFailure(`unknown flag ${unknownFlagName} for hearthkit ${match.commandPath}`),
+    )
+  }
+
+  return buildCliInvocation({
+    commandPath: match.commandPath,
+    commandArguments: match.commandArguments,
+    flagValues: split.flagValues,
+    presentBooleanFlagNames: split.presentBooleanFlagNames,
+    context: options.context,
+  })
+}
+
+/** Wraps a failure as the rejected branch, so every early return below stays one line. */
+function rejectedInvocation(failure: CliFailure): CliInvocationParse {
+  return { kind: 'cli-invocation-rejected', failure }
+}
+
+/** Reads a word the arity check already guaranteed; an empty string still fails its schema below. */
+function commandArgumentAt(commandArguments: readonly string[], index: number): string {
+  return commandArguments[index] ?? ''
+}
+
+/**
+ * Separates flags from command words in one pass. Both --flag value and --flag=value are accepted;
+ * a lone dash-prefixed word that is in neither catalogue is an unknown flag, never a command word.
+ */
+function splitCliArguments(argv: readonly string[]): CliArgumentSplit {
+  const commandWords: string[] = []
+  const flagValues = new Map<string, string>()
+  const presentBooleanFlagNames = new Set<string>()
+  const givenFlagNames = new Set<string>()
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index] ?? ''
+    if (!token.startsWith('-')) {
+      commandWords.push(token)
+      continue
+    }
+
+    const equalsIndex = token.indexOf('=')
+    const flagName = equalsIndex === -1 ? token : token.slice(0, equalsIndex)
+    const inlineValue = equalsIndex === -1 ? undefined : token.slice(equalsIndex + 1)
+
+    if (isValueFlagName(flagName)) {
+      const flagValue = inlineValue ?? argv[index + 1]
+      if (inlineValue === undefined) {
+        index += 1
+      }
+      if (flagValue === undefined || flagValue === '') {
+        return {
+          kind: 'cli-arguments-rejected',
+          failure: cliUsageInvalidFailure(`${flagName} needs a value`),
+        }
+      }
+      flagValues.set(flagName, flagValue)
+      givenFlagNames.add(flagName)
+      continue
+    }
+
+    if (isBooleanFlagName(flagName)) {
+      if (inlineValue !== undefined) {
+        return {
+          kind: 'cli-arguments-rejected',
+          failure: cliUsageInvalidFailure(`${flagName} takes no value`),
+        }
+      }
+      presentBooleanFlagNames.add(flagName)
+      givenFlagNames.add(flagName)
+      continue
+    }
+
+    return {
+      kind: 'cli-arguments-rejected',
+      failure: cliUsageInvalidFailure(`unknown flag ${flagName}`),
+    }
+  }
+
+  return {
+    kind: 'cli-arguments-split',
+    commandWords,
+    flagValues,
+    presentBooleanFlagNames,
+    givenFlagNames,
+  }
+}
+
+/** True when the word is one of the flags that consumes the next argv word. */
+function isValueFlagName(flagName: string): boolean {
+  return (valueFlagNames as readonly string[]).includes(flagName)
+}
+
+/** True when the word is one of the standalone flags. */
+function isBooleanFlagName(flagName: string): boolean {
+  return (booleanFlagNames as readonly string[]).includes(flagName)
+}
+
+/** Which command the leading words name, and the words left over for it to consume. */
+type CommandPathMatch =
+  | { kind: 'command-path-matched'; commandPath: CliCommandPath; commandArguments: string[] }
+  | {
+      kind: 'command-argument-count-wrong'
+      commandPath: CliCommandPath
+      commandArguments: string[]
+    }
+  | { kind: 'command-path-unknown' }
+
+/**
+ * Matches the longest command path first, so `dev infra up` wins over `dev` and later phases can
+ * append longer paths to the enum without disturbing the ones already here.
+ */
+function matchCommandPath(commandWords: readonly string[]): CommandPathMatch {
+  const commandPathsByLength = cliCommandPathSchema.options.toSorted(
+    (left, right) => right.split(' ').length - left.split(' ').length,
+  )
+
+  for (const commandPath of commandPathsByLength) {
+    const pathWords = commandPath.split(' ')
+    const isPrefix = pathWords.every((pathWord, index) => commandWords[index] === pathWord)
+    if (!isPrefix) {
+      continue
+    }
+    const commandArguments = commandWords.slice(pathWords.length)
+    if (commandArguments.length !== commandArgumentCountByPath[commandPath]) {
+      return { kind: 'command-argument-count-wrong', commandPath, commandArguments }
+    }
+    return { kind: 'command-path-matched', commandPath, commandArguments }
+  }
+
+  return { kind: 'command-path-unknown' }
+}
+
+/** Turns a matched command plus its flags into the invocation shape the handlers receive. */
+function buildCliInvocation(options: {
+  commandPath: CliCommandPath
+  commandArguments: readonly string[]
+  flagValues: Map<string, string>
+  presentBooleanFlagNames: ReadonlySet<string>
+  context: CliRuntimeContext
+}): CliInvocationParse {
+  const { commandPath, commandArguments, flagValues, context } = options
+
+  if (commandPath === 'dev' || commandPath === 'dev infra up' || commandPath === 'dev infra down') {
+    return { kind: 'cli-invocation-parsed', invocation: { commandPath } }
+  }
+
+  if (commandPath === 'doctor') {
+    return {
+      kind: 'cli-invocation-parsed',
+      invocation: { commandPath, jsonOutput: options.presentBooleanFlagNames.has('--json') },
+    }
+  }
+
+  if (commandPath === 'payments sync') {
+    const givenCatalogPath = flagValues.get('--catalog') ?? defaultPaymentsCatalogPath
+    return {
+      kind: 'cli-invocation-parsed',
+      invocation: {
+        commandPath,
+        catalogPath: isAbsolute(givenCatalogPath)
+          ? givenCatalogPath
+          : resolve(context.workingDirectoryPath, givenCatalogPath),
+      },
+    }
+  }
+
+  if (commandPath === 'db migrate') {
+    const databaseUrlCandidate =
+      flagValues.get('--database-url') ??
+      readEnvironmentVariableValue(context.environmentVariables, projectDatabaseUrlEnvVariableName)
+    if (databaseUrlCandidate === undefined) {
+      return rejectedInvocation(
+        databaseUrlMissingFailure(
+          'is not set and --database-url was not given; hearthkit db migrate needs the project connection',
+        ),
+      )
+    }
+    const parsedDatabaseUrl = postgresConnectionStringSchema.safeParse(databaseUrlCandidate)
+    if (!parsedDatabaseUrl.success) {
+      return rejectedInvocation(
+        databaseUrlInvalidFailure(
+          `not a postgres:// or postgresql:// url (given: ${databaseUrlCandidate})`,
+        ),
+      )
+    }
+    return {
+      kind: 'cli-invocation-parsed',
+      invocation: {
+        commandPath,
+        databaseUrl: parsedDatabaseUrl.data,
+        migrationsFolderPath: flagValues.get('--migrations-folder') ?? defaultMigrationsFolderPath,
+      },
+    }
+  }
+
+  const parsedDatabaseName = projectDatabaseNameSchema.safeParse(
+    commandArgumentAt(commandArguments, 0),
+  )
+  if (!parsedDatabaseName.success) {
+    return rejectedInvocation(
+      cliUsageInvalidFailure(
+        `${commandPath} needs a lowercase snake_case database name of at most 63 characters (given: ${JSON.stringify(commandArgumentAt(commandArguments, 0))})`,
+      ),
+    )
+  }
+
+  const adminResolution = resolveAdminDatabaseUrl({
+    adminDatabaseUrlFlagValue: flagValues.get('--admin-database-url'),
+    environmentVariables: context.environmentVariables,
+  })
+  if (adminResolution.kind === 'admin-database-url-rejected') {
+    return rejectedInvocation(adminResolution.failure)
+  }
+
+  const projectDatabaseName = parsedDatabaseName.data
+  const adminDatabaseUrl = adminResolution.adminDatabaseUrl
+
+  if (commandPath === 'db create' || commandPath === 'db drop') {
+    return {
+      kind: 'cli-invocation-parsed',
+      invocation: { commandPath, projectDatabaseName, adminDatabaseUrl },
+    }
+  }
+
+  if (commandPath === 'db backup') {
+    return {
+      kind: 'cli-invocation-parsed',
+      invocation: {
+        commandPath,
+        projectDatabaseName,
+        adminDatabaseUrl,
+        backupFilePath:
+          flagValues.get('--backup-file') ??
+          buildDefaultBackupFilePath({
+            workingDirectoryPath: context.workingDirectoryPath,
+            projectDatabaseName,
+          }),
+      },
+    }
+  }
+
+  return {
+    kind: 'cli-invocation-parsed',
+    invocation: {
+      commandPath,
+      projectDatabaseName,
+      adminDatabaseUrl,
+      backupFilePath: commandArgumentAt(commandArguments, 1),
+    },
+  }
+}

package/src/read-environment-variable-value.ts

@@ -0,0 +1,14 @@
+/**
+ * Reads one variable from the CLI's environment. An empty string counts as unset, matching the rule
+ * @hearthkit/config applies at boot, so `HEARTHKIT_ADMIN_DATABASE_URL=` falls through to the default.
+ */
+export function readEnvironmentVariableValue(
+  environmentVariables: Record<string, string | undefined>,
+  variableName: string,
+): string | undefined {
+  const value = environmentVariables[variableName]
+  if (value === undefined || value.trim() === '') {
+    return undefined
+  }
+  return value
+}

package/src/read-project-infra-manifest.ts

@@ -0,0 +1,99 @@
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { z } from 'zod'
+import {
+  localInfraServiceNameSchema,
+  localInfraServicesByHearthkitPackage,
+  type HearthkitProjectName,
+  type LocalInfraServiceName,
+} from './cli-contract.ts'
+import type { CliRuntimeContext } from './cli-runtime-context.ts'
+import { deriveHearthkitProjectName } from './derive-hearthkit-project-name.ts'
+
+/** The only fields of a project's package.json this package looks at; anything else is ignored, not rejected. */
+const projectManifestSchema = z.object({
+  name: z.string().optional(),
+  dependencies: z.record(z.string(), z.string()).optional(),
+  devDependencies: z.record(z.string(), z.string()).optional(),
+})
+
+/** What the working directory's package.json said, or why it could not be used as a manifest. */
+export type ProjectInfraManifestOutcome =
+  | {
+      kind: 'project-infra-manifest-read'
+      manifestPath: string
+      hearthkitProjectName: HearthkitProjectName
+      infraServices: LocalInfraServiceName[]
+    }
+  | { kind: 'project-infra-manifest-unreadable'; manifestPath: string; detail: string }
+
+/**
+ * Reads ./package.json and answers which local infra services the installed hearthkit packages ask
+ * for. A manifest that is absent, unreadable, or not an object is one outcome: there is nothing to
+ * derive services from either way, and the caller reports it as project-manifest-missing.
+ */
+export async function readProjectInfraManifest(
+  context: CliRuntimeContext,
+): Promise<ProjectInfraManifestOutcome> {
+  const manifestPath = join(context.workingDirectoryPath, 'package.json')
+
+  let manifestFileContent: string
+  try {
+    manifestFileContent = await readFile(manifestPath, 'utf8')
+  } catch (error) {
+    return {
+      kind: 'project-infra-manifest-unreadable',
+      manifestPath,
+      detail: `could not be read (${error instanceof Error ? error.message : String(error)})`,
+    }
+  }
+
+  let manifestValue: unknown
+  try {
+    manifestValue = JSON.parse(manifestFileContent)
+  } catch (error) {
+    return {
+      kind: 'project-infra-manifest-unreadable',
+      manifestPath,
+      detail: `is not valid json (${error instanceof Error ? error.message : String(error)})`,
+    }
+  }
+
+  const parsedManifest = projectManifestSchema.safeParse(manifestValue)
+  if (!parsedManifest.success) {
+    return {
+      kind: 'project-infra-manifest-unreadable',
+      manifestPath,
+      detail: 'is not a package manifest with name and dependency fields',
+    }
+  }
+
+  return {
+    kind: 'project-infra-manifest-read',
+    manifestPath,
+    hearthkitProjectName: deriveHearthkitProjectName(parsedManifest.data.name),
+    infraServices: readInfraServicesFromDependencies({
+      ...parsedManifest.data.dependencies,
+      ...parsedManifest.data.devDependencies,
+    }),
+  }
+}
+
+/**
+ * Maps installed hearthkit packages to the services they need. The map is one-to-many, so two
+ * packages can name the same service and the Set collapses it to one. The returned order comes from
+ * localInfraServiceNameSchema.options and never from the map or the manifest, which is what keeps one
+ * manifest producing one compose file.
+ */
+function readInfraServicesFromDependencies(
+  dependencyVersionByName: Record<string, string>,
+): LocalInfraServiceName[] {
+  const neededServiceNames = new Set<LocalInfraServiceName>(
+    Object.entries(localInfraServicesByHearthkitPackage)
+      .filter(([packageName]) => dependencyVersionByName[packageName] !== undefined)
+      .flatMap(([, serviceNames]) => serviceNames),
+  )
+  return localInfraServiceNameSchema.options.filter((serviceName) =>
+    neededServiceNames.has(serviceName),
+  )
+}

package/src/report-cli-outcome.ts

@@ -0,0 +1,139 @@
+import {
+  cliDbBackupCompleteLinePrefix,
+  cliDbCreateCredentialsWarningPrefix,
+  cliDbDropCompleteLinePrefix,
+  cliDbMigrateCompleteLinePrefix,
+  cliDbRestoreCompleteLinePrefix,
+  cliDevInfraDownCompleteLinePrefix,
+  cliDevInfraUpCompleteLinePrefix,
+  cliPaymentsSyncCompleteLinePrefix,
+  stripeSecretKeyEnvVariableName,
+  type CliCommandInvocation,
+  type CliCommandResult,
+  type CliExitCode,
+  type DoctorCheckResult,
+} from './cli-contract.ts'
+import { writeStandardErrorLine, writeStandardOutputLine } from './cli-output-streams.ts'
+import { formatDoctorCheckTable, formatDoctorJsonReport } from './format-doctor-report.ts'
+
+/** Exit code for a command that did what it was asked. */
+const successExitCode = 0
+
+/** Exit code for a command that was understood but could not be carried out. */
+const operationalFailureExitCode = 1
+
+/** Exit code for a command line that could not be understood at all. */
+const usageFailureExitCode = 2
+
+/**
+ * Writes everything one command run prints and returns the code the process should exit with. All
+ * stream writes live here, so the single stdout line per command and the stderr-only failure rule
+ * are enforced in one place rather than in every handler.
+ */
+export function reportCliOutcome(options: {
+  result: CliCommandResult
+  invocation: CliCommandInvocation | undefined
+}): CliExitCode {
+  const { result, invocation } = options
+
+  switch (result.kind) {
+    case 'db-create-command-succeeded':
+      writeStandardErrorLine(
+        `${cliDbCreateCredentialsWarningPrefix} the connection string below holds a generated password shown this once and never stored; copy it into your .env.local now`,
+      )
+      writeStandardOutputLine(result.connectionString)
+      return successExitCode
+
+    case 'db-drop-command-succeeded':
+      writeStandardOutputLine(
+        `${cliDbDropCompleteLinePrefix} ${result.projectDatabaseName} and its role are gone`,
+      )
+      return successExitCode
+
+    case 'db-migrate-command-succeeded':
+      writeStandardOutputLine(
+        `${cliDbMigrateCompleteLinePrefix} applied ${result.appliedMigrationCount} migration(s)`,
+      )
+      return successExitCode
+
+    case 'db-backup-command-succeeded':
+      writeStandardOutputLine(
+        `${cliDbBackupCompleteLinePrefix} ${result.projectDatabaseName} written to ${result.backupFilePath} (${result.backupByteCount} bytes)`,
+      )
+      return successExitCode
+
+    case 'db-restore-command-succeeded':
+      writeStandardOutputLine(
+        `${cliDbRestoreCompleteLinePrefix} ${result.projectDatabaseName} restored from ${result.backupFilePath}`,
+      )
+      return successExitCode
+
+    case 'dev-infra-up-succeeded':
+      writeStandardOutputLine(
+        `${cliDevInfraUpCompleteLinePrefix} ${
+          result.startedInfraServices.length === 0
+            ? 'no local infra services needed'
+            : `started ${result.startedInfraServices.join(', ')}`
+        }`,
+      )
+      return successExitCode
+
+    case 'dev-infra-down-succeeded':
+      writeStandardOutputLine(`${cliDevInfraDownCompleteLinePrefix} local infra services stopped`)
+      return successExitCode
+
+    // next dev already streamed its own stdio, so there is nothing left to print for it.
+    case 'dev-command-exited':
+      return result.nextDevExitCode
+
+    case 'doctor-report':
+      printDoctorReport(result.checks, true, readDoctorJsonOutput(invocation))
+      return successExitCode
+
+    case 'doctor-checks-failed':
+      printDoctorReport(result.checks, false, readDoctorJsonOutput(invocation))
+      writeStandardErrorLine(result.message)
+      return operationalFailureExitCode
+
+    case 'payments-sync-command-succeeded':
+      writeStandardOutputLine(
+        `${cliPaymentsSyncCompleteLinePrefix} ${String(result.createdPriceCount)} created, ${String(result.replacedPriceCount)} replaced, ${String(result.unchangedPriceCount)} unchanged from ${result.catalogPath}`,
+      )
+      return successExitCode
+
+    case 'cli-usage-invalid':
+      writeStandardErrorLine(result.message)
+      return usageFailureExitCode
+
+    // The payments message names the field it rejected, never the variable, so the guidance above it
+    // does: an unset key is the only way the env object can be wrong here.
+    case 'cli-payments-sync-failed':
+      writeStandardErrorLine(
+        `hearthkit payments sync needs a Stripe test-mode key in ${stripeSecretKeyEnvVariableName}; the message below is @hearthkit/payments' own`,
+      )
+      writeStandardErrorLine(result.message)
+      return operationalFailureExitCode
+
+    default:
+      writeStandardErrorLine(result.message)
+      return operationalFailureExitCode
+  }
+}
+
+/** Whether doctor was asked for JSON; any other command's invocation means the question does not apply. */
+function readDoctorJsonOutput(invocation: CliCommandInvocation | undefined): boolean {
+  return invocation !== undefined && invocation.commandPath === 'doctor' && invocation.jsonOutput
+}
+
+/** Prints the report on stdout in the shape the operator asked for, whether or not every check passed. */
+function printDoctorReport(
+  checks: DoctorCheckResult[],
+  allDoctorChecksPassed: boolean,
+  jsonOutput: boolean,
+): void {
+  writeStandardOutputLine(
+    jsonOutput
+      ? formatDoctorJsonReport({ checks, allDoctorChecksPassed })
+      : formatDoctorCheckTable(checks),
+  )
+}

package/src/resolve-admin-database-url.ts

@@ -0,0 +1,72 @@
+import { postgresConnectionStringSchema, type PostgresConnectionString } from '@hearthkit/db'
+import {
+  adminDatabaseUrlEnvVariableName,
+  defaultLocalAdminDatabaseUrl,
+  type CliFailure,
+} from './cli-contract.ts'
+import { adminDatabaseUrlInvalidFailure } from './cli-failure-results.ts'
+import { readEnvironmentVariableValue } from './read-environment-variable-value.ts'
+
+/** Where the admin connection came from, kept on the resolution so a failure can name the source the operator must fix. */
+export type AdminDatabaseUrlSource = 'flag' | 'environment' | 'default'
+
+/** A resolved admin connection, or the failure to report when the winning candidate is not a postgres(ql) URL. */
+export type AdminDatabaseUrlResolution =
+  | {
+      kind: 'admin-database-url-resolved'
+      adminDatabaseUrl: PostgresConnectionString
+      adminDatabaseUrlSource: AdminDatabaseUrlSource
+    }
+  | {
+      kind: 'admin-database-url-rejected'
+      failure: Extract<CliFailure, { kind: 'admin-database-url-invalid' }>
+    }
+
+/**
+ * Applies the contract's precedence: --admin-database-url, then HEARTHKIT_ADMIN_DATABASE_URL, then
+ * the local compose default. Only the winning candidate is validated, so a broken environment
+ * variable cannot spoil a run that passed the flag.
+ */
+export function resolveAdminDatabaseUrl(options: {
+  adminDatabaseUrlFlagValue: string | undefined
+  environmentVariables: Record<string, string | undefined>
+}): AdminDatabaseUrlResolution {
+  const environmentValue = readEnvironmentVariableValue(
+    options.environmentVariables,
+    adminDatabaseUrlEnvVariableName,
+  )
+
+  const candidate =
+    options.adminDatabaseUrlFlagValue !== undefined
+      ? { value: options.adminDatabaseUrlFlagValue, source: 'flag' as const }
+      : environmentValue !== undefined
+        ? { value: environmentValue, source: 'environment' as const }
+        : { value: defaultLocalAdminDatabaseUrl as string, source: 'default' as const }
+
+  const parsed = postgresConnectionStringSchema.safeParse(candidate.value)
+  if (!parsed.success) {
+    return {
+      kind: 'admin-database-url-rejected',
+      failure: adminDatabaseUrlInvalidFailure(
+        `${describeAdminDatabaseUrlSource(candidate.source)} is not a postgres:// or postgresql:// url (given: ${candidate.value})`,
+      ),
+    }
+  }
+
+  return {
+    kind: 'admin-database-url-resolved',
+    adminDatabaseUrl: parsed.data,
+    adminDatabaseUrlSource: candidate.source,
+  }
+}
+
+/** Names the losing source in operator words, so the message says which knob to turn. */
+function describeAdminDatabaseUrlSource(source: AdminDatabaseUrlSource): string {
+  if (source === 'flag') {
+    return '--admin-database-url'
+  }
+  if (source === 'environment') {
+    return adminDatabaseUrlEnvVariableName
+  }
+  return 'the default local admin url'
+}