@hearthkit/cli 0.1.0

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@hearthkit/cli",
+  "version": "0.1.0",
+  "description": "The hearthkit binary: db lifecycle, dev infra, and doctor commands over @hearthkit/db",
+  "homepage": "https://github.com/chrisdevelops/hearthkit/tree/main/packages/cli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chrisdevelops/hearthkit.git",
+    "directory": "packages/cli"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "bin": {
+    "hearthkit": "./src/hearthkit-bin-entry.js"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": "24.20.0"
+  },
+  "dependencies": {
+    "zod": "4.4.3",
+    "@hearthkit/config": "0.1.0",
+    "@hearthkit/payments": "0.1.0",
+    "@hearthkit/db": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "typescript": "7.0.2",
+    "vitest": "4.1.11"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/cli-contract.ts

@@ -0,0 +1,423 @@
+import {
+  dbFailureSchema,
+  postgresConnectionStringSchema,
+  projectDatabaseNameSchema,
+} from '@hearthkit/db'
+import {
+  paymentsFailureSchema,
+  paymentsSyncedPriceSchema,
+} from '@hearthkit/payments/payments-contract'
+import { z } from 'zod'
+
+/** Unique literal prefix of the error message for an unknown command, unknown flag, or schema-invalid argument; exit code 2. */
+export const cliUsageErrorPrefix = 'hearthkit cli usage:'
+
+/** Unique literal prefix of the error message when the resolved admin database URL is not a postgres(ql) URL. */
+export const cliAdminUrlInvalidErrorPrefix = 'hearthkit cli admin url invalid:'
+
+/** Unique literal prefix of the error message when db migrate has neither a --database-url flag nor DATABASE_URL set; the message names the literal DATABASE_URL variable after the prefix. */
+export const cliDatabaseUrlMissingErrorPrefix = 'hearthkit cli database url missing:'
+
+/** Unique literal prefix of the error message when the provided project database URL is not a postgres(ql) URL. */
+export const cliDatabaseUrlInvalidErrorPrefix = 'hearthkit cli database url invalid:'
+
+/** Unique literal prefix of the error message when the docker CLI is missing from PATH or the daemon is not running. */
+export const cliDockerUnavailableErrorPrefix = 'hearthkit cli docker unavailable:'
+
+/** Unique literal prefix of the error message when a docker compose invocation exits nonzero. */
+export const cliInfraComposeFailedErrorPrefix = 'hearthkit cli infra compose failed:'
+
+/** Unique literal prefix of the error message when compose generation is needed but the working directory has no package.json. */
+export const cliProjectManifestMissingErrorPrefix = 'hearthkit cli project manifest missing:'
+
+/** Unique literal prefix of the error message when the generated docker-compose.yml cannot be written. */
+export const cliComposeFileUnwritableErrorPrefix = 'hearthkit cli compose file unwritable:'
+
+/** Unique literal prefix of the error message when hearthkit dev finds no runnable next binary in the project. */
+export const cliNextDevUnavailableErrorPrefix = 'hearthkit cli next dev unavailable:'
+
+/** Unique literal prefix of the stderr line printed when at least one doctor check did not pass; exit code 1. */
+export const cliDoctorFailedErrorPrefix = 'hearthkit doctor failed:'
+
+/** Unique literal prefix of the error message when the payments catalog file (--catalog or ./payments-catalog.ts) does not exist; the message carries the resolved path. */
+export const cliPaymentsCatalogNotFoundErrorPrefix = 'hearthkit cli payments catalog not found:'
+
+/** Unique literal prefix of the error message when the payments catalog file exists but cannot be imported or exports no catalog under the expected name. */
+export const cliPaymentsCatalogUnloadableErrorPrefix = 'hearthkit cli payments catalog unloadable:'
+
+/** Unique literal prefix of the error message when @hearthkit/payments returned a failure while building the client or syncing; the payments message follows the prefix. */
+export const cliPaymentsSyncFailedErrorPrefix = 'hearthkit cli payments sync failed:'
+
+/** Unique literal prefix of the one-time stderr warning printed by hearthkit db create that the credentials are shown once and never persisted. */
+export const cliDbCreateCredentialsWarningPrefix = 'hearthkit db create warning:'
+
+/** Unique literal prefix of the single stdout success line of hearthkit db drop. */
+export const cliDbDropCompleteLinePrefix = 'hearthkit db drop complete:'
+
+/** Unique literal prefix of the single stdout success line of hearthkit db migrate. */
+export const cliDbMigrateCompleteLinePrefix = 'hearthkit db migrate complete:'
+
+/** Unique literal prefix of the single stdout success line of hearthkit db backup. */
+export const cliDbBackupCompleteLinePrefix = 'hearthkit db backup complete:'
+
+/** Unique literal prefix of the single stdout success line of hearthkit db restore. */
+export const cliDbRestoreCompleteLinePrefix = 'hearthkit db restore complete:'
+
+/** Unique literal prefix of the single stdout success line of hearthkit dev infra up. */
+export const cliDevInfraUpCompleteLinePrefix = 'hearthkit dev infra up complete:'
+
+/** Unique literal prefix of the single stdout success line of hearthkit dev infra down. */
+export const cliDevInfraDownCompleteLinePrefix = 'hearthkit dev infra down complete:'
+
+/** Unique literal prefix of the single stdout success line of hearthkit payments sync; the line carries the created, replaced and unchanged price counts. */
+export const cliPaymentsSyncCompleteLinePrefix = 'hearthkit payments sync complete:'
+
+/** Name of the env variable hearthkit payments sync reads for the Stripe key; the same variable @hearthkit/payments declares, read with the empty-string-is-unset rule. */
+export const stripeSecretKeyEnvVariableName = 'STRIPE_SECRET_KEY'
+
+/** Default catalog module path, relative to cwd, when hearthkit payments sync is run without --catalog; the file templates/app ships. */
+export const defaultPaymentsCatalogPath = './payments-catalog.ts'
+
+/** Named export hearthkit payments sync reads off the catalog module first, matching templates/app/payments-catalog.ts; a default export is the fallback when this name is absent. */
+export const paymentsCatalogModuleExportName = 'appPaymentsCatalog'
+
+/** Name of the operator env variable holding the admin connection; overridden by --admin-database-url, overrides the local default. */
+export const adminDatabaseUrlEnvVariableName = 'HEARTHKIT_ADMIN_DATABASE_URL'
+
+/** Fallback admin connection when neither flag nor env provides one; matches the repo and generated compose Postgres service. */
+export const defaultLocalAdminDatabaseUrl = postgresConnectionStringSchema.parse(
+  'postgresql://hearthkit:hearthkit@localhost:5432/hearthkit',
+)
+
+/** Default drizzle-kit output folder used by hearthkit db migrate when --migrations-folder is not given. */
+export const defaultMigrationsFolderPath = './drizzle'
+
+/** Default directory (relative to cwd) where hearthkit db backup writes archives when --backup-file is not given. */
+export const defaultBackupDirectoryPath = './backups'
+
+/** Env schema fragment this package owns; operator-time variable read by the CLI itself, never composed into app boot config. */
+export const cliEnvSchemaFragment = z.object({
+  HEARTHKIT_ADMIN_DATABASE_URL: postgresConnectionStringSchema.optional(),
+})
+
+/** Hearthkit project name; lowercase kebab-case used for compose project, container, and volume names, distinct from ProjectDatabaseName. */
+export const hearthkitProjectNameSchema = z
+  .string()
+  .regex(/^[a-z][a-z0-9-]*$/)
+  .max(63)
+  .brand<'HearthkitProjectName'>()
+
+/** Branded hearthkit project name; derived from package.json name by stripping the scope and sanitizing to kebab-case. */
+export type HearthkitProjectName = z.infer<typeof hearthkitProjectNameSchema>
+
+/** The three local infra services from plan section 6; the only values infraServices accepts, the only names startedInfraServices reports, and the fixed order derived services are emitted in, which is never the key order of localInfraServicesByHearthkitPackage. */
+export const localInfraServiceNameSchema = z.enum(['postgres', 'minio', 'mailpit'])
+
+/** Local infra service name; postgres for db and auth, minio for storage, mailpit for email and auth. */
+export type LocalInfraServiceName = z.infer<typeof localInfraServiceNameSchema>
+
+/** Pinned container image per selectable local infra service; the one place to bump these three (the bucket init container is pinned by localStorageBucketInitImage). */
+export const localInfraServiceImageByName = {
+  postgres: 'postgres:17',
+  minio: 'minio/minio:RELEASE.2025-09-07T16-13-09Z',
+  mailpit: 'axllent/mailpit:v1.31',
+} as const satisfies Record<LocalInfraServiceName, string>
+
+/** Which local infra services each hearthkit package pulls in when dev infra up derives services from package.json; the derived set is deduplicated and emitted in localInfraServiceNameSchema option order. */
+export const localInfraServicesByHearthkitPackage = {
+  '@hearthkit/db': ['postgres'],
+  '@hearthkit/storage': ['minio'],
+  '@hearthkit/email': ['mailpit'],
+  '@hearthkit/auth': ['postgres', 'mailpit'],
+} as const satisfies Record<string, readonly LocalInfraServiceName[]>
+
+/** Compose service key of the container that creates the local storage bucket and then stays running on purpose, because docker compose up --wait exits 1 when a service it started has exited; deliberately not a LocalInfraServiceName because no project selects it. */
+export const localStorageBucketInitServiceName = 'minio-init'
+
+/** Pinned image of the bucket init container; the one place to bump it, kept out of localInfraServiceImageByName because that map is keyed by selectable services. */
+export const localStorageBucketInitImage = 'minio/mc:RELEASE.2025-08-13T08-35-41Z'
+
+/** Local development bucket name; the S3 and R2 intersection, so the same string is valid against either and against MinIO. */
+export const localStorageBucketNameSchema = z
+  .string()
+  .min(3)
+  .max(63)
+  .regex(/^[a-z0-9][a-z0-9-]*[a-z0-9]$/)
+  .brand<'LocalStorageBucketName'>()
+
+/** Branded local storage bucket name; what dev infra up creates in MinIO and what STORAGE_BUCKET holds during local development. */
+export type LocalStorageBucketName = z.infer<typeof localStorageBucketNameSchema>
+
+/** Signature of deriveLocalStorageBucketName: pure and total, truncating the project name so every valid project name yields a valid bucket name. */
+export type DeriveLocalStorageBucketName = (
+  hearthkitProjectName: HearthkitProjectName,
+) => LocalStorageBucketName
+
+/** Options for generateLocalInfraCompose; infraServices must name at least one service, duplicates are a caller bug, and the bucket name is derived from hearthkitProjectName rather than passed in. */
+export const generateLocalInfraComposeOptionsSchema = z.object({
+  hearthkitProjectName: hearthkitProjectNameSchema,
+  infraServices: z.array(localInfraServiceNameSchema).min(1),
+})
+
+/** Options type for generateLocalInfraCompose. */
+export type GenerateLocalInfraComposeOptions = z.infer<
+  typeof generateLocalInfraComposeOptionsSchema
+>
+
+/** Signature of generateLocalInfraCompose: pure and deterministic, returns compose YAML using the localInfraServiceImageByName and localStorageBucketInitImage pins. */
+export type GenerateLocalInfraCompose = (options: GenerateLocalInfraComposeOptions) => string
+
+/** Every command path the CLI dispatches; later phases append infra apply and vps bootstrap additively. */
+export const cliCommandPathSchema = z.enum([
+  'db create',
+  'db drop',
+  'db migrate',
+  'db backup',
+  'db restore',
+  'dev',
+  'dev infra up',
+  'dev infra down',
+  'doctor',
+  'payments sync',
+])
+
+/** Command path union; unknown paths are a cli-usage-invalid failure, never a silent no-op. */
+export type CliCommandPath = z.infer<typeof cliCommandPathSchema>
+
+/** A parsed invocation after flag and env resolution; admin and database URLs are already resolved per the contract's precedence, and catalogPath is absolute. */
+export const cliCommandInvocationSchema = z.discriminatedUnion('commandPath', [
+  z.object({
+    commandPath: z.literal('db create'),
+    projectDatabaseName: projectDatabaseNameSchema,
+    adminDatabaseUrl: postgresConnectionStringSchema,
+  }),
+  z.object({
+    commandPath: z.literal('db drop'),
+    projectDatabaseName: projectDatabaseNameSchema,
+    adminDatabaseUrl: postgresConnectionStringSchema,
+  }),
+  z.object({
+    commandPath: z.literal('db migrate'),
+    databaseUrl: postgresConnectionStringSchema,
+    migrationsFolderPath: z.string().min(1),
+  }),
+  z.object({
+    commandPath: z.literal('db backup'),
+    projectDatabaseName: projectDatabaseNameSchema,
+    adminDatabaseUrl: postgresConnectionStringSchema,
+    backupFilePath: z.string().min(1),
+  }),
+  z.object({
+    commandPath: z.literal('db restore'),
+    projectDatabaseName: projectDatabaseNameSchema,
+    adminDatabaseUrl: postgresConnectionStringSchema,
+    backupFilePath: z.string().min(1),
+  }),
+  z.object({ commandPath: z.literal('dev') }),
+  z.object({ commandPath: z.literal('dev infra up') }),
+  z.object({ commandPath: z.literal('dev infra down') }),
+  z.object({ commandPath: z.literal('doctor'), jsonOutput: z.boolean() }),
+  z.object({
+    commandPath: z.literal('payments sync'),
+    catalogPath: z.string().min(1),
+  }),
+])
+
+/** Parsed invocation union; the shape command handlers receive after resolution succeeds. */
+export type CliCommandInvocation = z.infer<typeof cliCommandInvocationSchema>
+
+/** The eight doctor check names; a check may be skipped only when its prerequisite check failed. */
+export const doctorCheckNameSchema = z.enum([
+  'node-version-supported',
+  'pnpm-command-available',
+  'docker-cli-available',
+  'docker-daemon-running',
+  'docker-compose-plugin-available',
+  'postgres-client-tools-version',
+  'admin-database-reachable',
+  'cli-env-variables-valid',
+])
+
+/** Doctor check name union; stable identifiers gates and --json consumers key on. */
+export type DoctorCheckName = z.infer<typeof doctorCheckNameSchema>
+
+/** One doctor check outcome; detail is a single human-readable line (found version, error summary, or skip reason). */
+export const doctorCheckResultSchema = z.object({
+  checkName: doctorCheckNameSchema,
+  status: z.enum(['pass', 'fail', 'skip']),
+  detail: z.string(),
+})
+
+/** Doctor check result; skip counts as not-passed for the exit code. */
+export type DoctorCheckResult = z.infer<typeof doctorCheckResultSchema>
+
+/** Exact object doctor --json prints as JSON on stdout, on success and on doctor-checks-failed alike (then allDoctorChecksPassed is false). */
+export const doctorJsonReportSchema = z.object({
+  checks: z.array(doctorCheckResultSchema).min(1),
+  allDoctorChecksPassed: z.boolean(),
+})
+
+/** Doctor --json stdout envelope type; the only machine-readable doctor output shape. */
+export type DoctorJsonReport = z.infer<typeof doctorJsonReportSchema>
+
+/** Every way a CLI command can fail; each variant's message starts with its unique prefix and is the last stderr line. */
+export const cliFailureSchema = z.discriminatedUnion('kind', [
+  z.object({
+    kind: z.literal('cli-usage-invalid'),
+    message: z.string().startsWith(cliUsageErrorPrefix),
+  }),
+  z.object({
+    kind: z.literal('admin-database-url-invalid'),
+    message: z.string().startsWith(cliAdminUrlInvalidErrorPrefix),
+  }),
+  z.object({
+    kind: z.literal('database-url-missing'),
+    message: z.string().startsWith(cliDatabaseUrlMissingErrorPrefix),
+  }),
+  z.object({
+    kind: z.literal('database-url-invalid'),
+    message: z.string().startsWith(cliDatabaseUrlInvalidErrorPrefix),
+  }),
+  z.object({
+    kind: z.literal('db-command-failed'),
+    dbFailure: dbFailureSchema,
+    message: z.string().startsWith('hearthkit db '),
+  }),
+  z.object({
+    kind: z.literal('docker-unavailable'),
+    message: z.string().startsWith(cliDockerUnavailableErrorPrefix),
+  }),
+  z.object({
+    kind: z.literal('infra-compose-failed'),
+    composeExitCode: z.number().int(),
+    composeStderrExcerpt: z.string(),
+    message: z.string().startsWith(cliInfraComposeFailedErrorPrefix),
+  }),
+  z.object({
+    kind: z.literal('project-manifest-missing'),
+    manifestPath: z.string().min(1),
+    message: z.string().startsWith(cliProjectManifestMissingErrorPrefix),
+  }),
+  z.object({
+    kind: z.literal('compose-file-unwritable'),
+    composeFilePath: z.string().min(1),
+    message: z.string().startsWith(cliComposeFileUnwritableErrorPrefix),
+  }),
+  z.object({
+    kind: z.literal('next-dev-unavailable'),
+    message: z.string().startsWith(cliNextDevUnavailableErrorPrefix),
+  }),
+  z.object({
+    kind: z.literal('doctor-checks-failed'),
+    checks: z.array(doctorCheckResultSchema).min(1),
+    failedCheckNames: z.array(doctorCheckNameSchema).min(1),
+    message: z.string().startsWith(cliDoctorFailedErrorPrefix),
+  }),
+  z.object({
+    kind: z.literal('cli-payments-catalog-not-found'),
+    catalogPath: z.string().min(1),
+    message: z.string().startsWith(cliPaymentsCatalogNotFoundErrorPrefix),
+  }),
+  z.object({
+    kind: z.literal('cli-payments-catalog-unloadable'),
+    catalogPath: z.string().min(1),
+    loadFailureDetail: z.string().min(1),
+    message: z.string().startsWith(cliPaymentsCatalogUnloadableErrorPrefix),
+  }),
+  z.object({
+    kind: z.literal('cli-payments-sync-failed'),
+    paymentsFailure: paymentsFailureSchema,
+    message: z.string().startsWith(cliPaymentsSyncFailedErrorPrefix),
+  }),
+])
+
+/** Discriminated failure union; db-command-failed wraps the DbFailure verbatim with the db message unchanged, cli-payments-sync-failed wraps the PaymentsFailure verbatim behind its own prefix. */
+export type CliFailure = z.infer<typeof cliFailureSchema>
+
+/** Success shapes per command; each mirrors what the single stdout line reports so gates can check either channel. */
+export const cliCommandSuccessSchema = z.discriminatedUnion('kind', [
+  z.object({
+    kind: z.literal('db-create-command-succeeded'),
+    projectDatabaseName: projectDatabaseNameSchema,
+    connectionString: postgresConnectionStringSchema,
+  }),
+  z.object({
+    kind: z.literal('db-drop-command-succeeded'),
+    projectDatabaseName: projectDatabaseNameSchema,
+  }),
+  z.object({
+    kind: z.literal('db-migrate-command-succeeded'),
+    appliedMigrationCount: z.number().int().min(0),
+  }),
+  z.object({
+    kind: z.literal('db-backup-command-succeeded'),
+    projectDatabaseName: projectDatabaseNameSchema,
+    backupFilePath: z.string().min(1),
+    backupByteCount: z.number().int().positive(),
+  }),
+  z.object({
+    kind: z.literal('db-restore-command-succeeded'),
+    projectDatabaseName: projectDatabaseNameSchema,
+    backupFilePath: z.string().min(1),
+  }),
+  z.object({
+    kind: z.literal('dev-infra-up-succeeded'),
+    startedInfraServices: z.array(localInfraServiceNameSchema),
+  }),
+  z.object({ kind: z.literal('dev-infra-down-succeeded') }),
+  z.object({
+    kind: z.literal('dev-command-exited'),
+    nextDevExitCode: z.number().int().min(0).max(255),
+  }),
+  z.object({
+    kind: z.literal('doctor-report'),
+    checks: z.array(doctorCheckResultSchema).min(1),
+    allDoctorChecksPassed: z.literal(true),
+  }),
+  z.object({
+    kind: z.literal('payments-sync-command-succeeded'),
+    catalogPath: z.string().min(1),
+    syncedPrices: z.array(paymentsSyncedPriceSchema).min(1),
+    createdPriceCount: z.number().int().min(0),
+    replacedPriceCount: z.number().int().min(0),
+    unchangedPriceCount: z.number().int().min(0),
+    stripeLivemode: z.boolean(),
+  }),
+])
+
+/** Command success union; doctor-report appears here only when every check passed, otherwise doctor-checks-failed is returned. */
+export type CliCommandSuccess = z.infer<typeof cliCommandSuccessSchema>
+
+/** Full result union of one CLI command run, for runtime validation in gates. */
+export const cliCommandResultSchema = z.union([cliCommandSuccessSchema, cliFailureSchema])
+
+/** Result type of one CLI command run: a success variant or a CliFailure. */
+export type CliCommandResult = z.infer<typeof cliCommandResultSchema>
+
+/** Process exit code of the bin: 0 success, 1 operational failure, 2 usage; hearthkit dev propagates next dev's code. */
+export const cliExitCodeSchema = z.number().int().min(0).max(255)
+
+/** Exit code type returned by runHearthkitCli and used by the bin wrapper. */
+export type CliExitCode = z.infer<typeof cliExitCodeSchema>
+
+/** Runtime shape of runHearthkitCli options; argv is command words and flags only, without the node and bin prefix. */
+export const runHearthkitCliOptionsSchema = z.object({
+  argv: z.array(z.string()),
+  cwd: z.string().min(1).optional(),
+  env: z.record(z.string(), z.string().optional()).optional(),
+})
+
+/** Options type for runHearthkitCli; cwd defaults to process.cwd() and env to process.env. */
+export type RunHearthkitCliOptions = z.infer<typeof runHearthkitCliOptionsSchema>
+
+/** What one CLI run produced; exitCode is what the bin exits with and result is the structured outcome gates validate. */
+export const cliRunOutcomeSchema = z.object({
+  exitCode: cliExitCodeSchema,
+  result: cliCommandResultSchema,
+})
+
+/** Outcome type of runHearthkitCli. */
+export type CliRunOutcome = z.infer<typeof cliRunOutcomeSchema>
+
+/** Signature of runHearthkitCli: parses argv, runs the command, writes stdout/stderr, never throws for a contract failure mode. */
+export type RunHearthkitCli = (options: RunHearthkitCliOptions) => Promise<CliRunOutcome>

package/src/cli-failure-results.ts

@@ -0,0 +1,175 @@
+import type { DbFailure } from '@hearthkit/db'
+import type { PaymentsFailure } from '@hearthkit/payments/payments-contract'
+import {
+  cliAdminUrlInvalidErrorPrefix,
+  cliComposeFileUnwritableErrorPrefix,
+  cliDatabaseUrlInvalidErrorPrefix,
+  cliDatabaseUrlMissingErrorPrefix,
+  cliDockerUnavailableErrorPrefix,
+  cliDoctorFailedErrorPrefix,
+  cliInfraComposeFailedErrorPrefix,
+  cliNextDevUnavailableErrorPrefix,
+  cliPaymentsCatalogNotFoundErrorPrefix,
+  cliPaymentsCatalogUnloadableErrorPrefix,
+  cliPaymentsSyncFailedErrorPrefix,
+  cliProjectManifestMissingErrorPrefix,
+  cliUsageErrorPrefix,
+  type CliFailure,
+  type DoctorCheckName,
+  type DoctorCheckResult,
+} from './cli-contract.ts'
+
+/** Every failure this package returns is built here, so each message keeps its unique literal prefix in one place. */
+type CliFailureOf<TKind extends CliFailure['kind']> = Extract<CliFailure, { kind: TKind }>
+
+/** How many characters of a compose stderr stream travel back in the failure; enough to name the cause, short enough to print. */
+const composeStandardErrorExcerptLimit = 2000
+
+/** Unknown command, unknown flag, missing argument, or an argument that fails its schema; the only exit-2 failure. */
+export function cliUsageInvalidFailure(detail: string): CliFailureOf<'cli-usage-invalid'> {
+  return {
+    kind: 'cli-usage-invalid',
+    message: `${cliUsageErrorPrefix} ${detail}`,
+  }
+}
+
+/** The admin URL resolved from the flag or the environment is not a postgres(ql) URL, so no database work was attempted. */
+export function adminDatabaseUrlInvalidFailure(
+  detail: string,
+): CliFailureOf<'admin-database-url-invalid'> {
+  return {
+    kind: 'admin-database-url-invalid',
+    message: `${cliAdminUrlInvalidErrorPrefix} ${detail}`,
+  }
+}
+
+/** db migrate ran with neither --database-url nor DATABASE_URL; the message names the variable right after the prefix. */
+export function databaseUrlMissingFailure(detail: string): CliFailureOf<'database-url-missing'> {
+  return {
+    kind: 'database-url-missing',
+    message: `${cliDatabaseUrlMissingErrorPrefix} DATABASE_URL ${detail}`,
+  }
+}
+
+/** The project-scoped database URL given on the command line or in the environment is not a postgres(ql) URL. */
+export function databaseUrlInvalidFailure(detail: string): CliFailureOf<'database-url-invalid'> {
+  return {
+    kind: 'database-url-invalid',
+    message: `${cliDatabaseUrlInvalidErrorPrefix} ${detail}`,
+  }
+}
+
+/** Carries a @hearthkit/db failure out unchanged; the CLI never re-words it, so the db prefix stays greppable. */
+export function dbCommandFailedFailure(dbFailure: DbFailure): CliFailureOf<'db-command-failed'> {
+  return {
+    kind: 'db-command-failed',
+    dbFailure,
+    message: dbFailure.message,
+  }
+}
+
+/** docker is not on PATH, or it is but the daemon did not answer docker info. */
+export function dockerUnavailableFailure(detail: string): CliFailureOf<'docker-unavailable'> {
+  return {
+    kind: 'docker-unavailable',
+    message: `${cliDockerUnavailableErrorPrefix} ${detail}`,
+  }
+}
+
+/** A docker compose invocation exited nonzero; the excerpt is compose's own words, truncated to stay printable. */
+export function infraComposeFailedFailure(options: {
+  composeArguments: readonly string[]
+  composeExitCode: number
+  composeStandardError: string
+}): CliFailureOf<'infra-compose-failed'> {
+  const reportedText = options.composeStandardError.trim()
+  const composeStderrExcerpt = (
+    reportedText === '' ? 'docker compose produced no diagnostic output' : reportedText
+  ).slice(0, composeStandardErrorExcerptLimit)
+  return {
+    kind: 'infra-compose-failed',
+    composeExitCode: options.composeExitCode,
+    composeStderrExcerpt,
+    message: `${cliInfraComposeFailedErrorPrefix} docker compose ${options.composeArguments.join(' ')} exited ${options.composeExitCode}: ${composeStderrExcerpt}`,
+  }
+}
+
+/** Compose generation was needed but the working directory holds no package.json to read the services from. */
+export function projectManifestMissingFailure(
+  manifestPath: string,
+  detail: string,
+): CliFailureOf<'project-manifest-missing'> {
+  return {
+    kind: 'project-manifest-missing',
+    manifestPath,
+    message: `${cliProjectManifestMissingErrorPrefix} ${manifestPath} ${detail}`,
+  }
+}
+
+/** The generated docker-compose.yml could not be written, so nothing was started. */
+export function composeFileUnwritableFailure(
+  composeFilePath: string,
+  detail: string,
+): CliFailureOf<'compose-file-unwritable'> {
+  return {
+    kind: 'compose-file-unwritable',
+    composeFilePath,
+    message: `${cliComposeFileUnwritableErrorPrefix} ${composeFilePath} ${detail}`,
+  }
+}
+
+/** hearthkit dev found no runnable next binary in the project's node_modules/.bin. */
+export function nextDevUnavailableFailure(detail: string): CliFailureOf<'next-dev-unavailable'> {
+  return {
+    kind: 'next-dev-unavailable',
+    message: `${cliNextDevUnavailableErrorPrefix} ${detail}`,
+  }
+}
+
+/** At least one doctor check did not pass; the whole report travels with the failure and still prints. */
+export function doctorChecksFailedFailure(
+  checks: DoctorCheckResult[],
+  failedCheckNames: DoctorCheckName[],
+): CliFailureOf<'doctor-checks-failed'> {
+  return {
+    kind: 'doctor-checks-failed',
+    checks,
+    failedCheckNames,
+    message: `${cliDoctorFailedErrorPrefix} ${failedCheckNames.join(', ')}`,
+  }
+}
+
+/** No file sits at the resolved catalog path, so nothing was imported and no Stripe key was read. */
+export function paymentsCatalogNotFoundFailure(
+  catalogPath: string,
+): CliFailureOf<'cli-payments-catalog-not-found'> {
+  return {
+    kind: 'cli-payments-catalog-not-found',
+    catalogPath,
+    message: `${cliPaymentsCatalogNotFoundErrorPrefix} ${catalogPath} does not exist; pass --catalog or add the file`,
+  }
+}
+
+/** The catalog file exists but importing it threw, or it exports no catalog under either accepted name. */
+export function paymentsCatalogUnloadableFailure(
+  catalogPath: string,
+  loadFailureDetail: string,
+): CliFailureOf<'cli-payments-catalog-unloadable'> {
+  return {
+    kind: 'cli-payments-catalog-unloadable',
+    catalogPath,
+    loadFailureDetail,
+    message: `${cliPaymentsCatalogUnloadableErrorPrefix} ${catalogPath}: ${loadFailureDetail}`,
+  }
+}
+
+/** Carries a @hearthkit/payments failure out behind this package's own prefix, with the payments message unchanged after it. */
+export function paymentsSyncFailedFailure(
+  paymentsFailure: PaymentsFailure,
+): CliFailureOf<'cli-payments-sync-failed'> {
+  return {
+    kind: 'cli-payments-sync-failed',
+    paymentsFailure,
+    message: `${cliPaymentsSyncFailedErrorPrefix} ${paymentsFailure.message}`,
+  }
+}

package/src/cli-output-streams.ts

@@ -0,0 +1,14 @@
+/** Writes the one machine-readable line a successful command prints; stdout carries nothing else. */
+export function writeStandardOutputLine(line: string): void {
+  process.stdout.write(`${line}\n`)
+}
+
+/** Writes one human line to stderr: guidance, progress, or the failure message, never machine-readable output. */
+export function writeStandardErrorLine(line: string): void {
+  process.stderr.write(`${line}\n`)
+}
+
+/** Forwards a child process's stderr through unchanged, so docker compose progress reaches the operator as it happens. */
+export function writeStandardErrorChunk(chunk: string): void {
+  process.stderr.write(chunk)
+}

package/src/cli-runtime-context.ts

@@ -0,0 +1,8 @@
+/**
+ * Where one command runs and what it may read. runHearthkitCli resolves this once from its options,
+ * so no handler below it reaches for process.cwd() or process.env and every gate can redirect both.
+ */
+export type CliRuntimeContext = {
+  workingDirectoryPath: string
+  environmentVariables: Record<string, string | undefined>
+}