@hearthkit/cli 0.1.0

package/src/default-backup-file-path.ts

@@ -0,0 +1,28 @@
+import { resolve } from 'node:path'
+import type { ProjectDatabaseName } from '@hearthkit/db'
+import { defaultBackupDirectoryPath } from './cli-contract.ts'
+
+/**
+ * Where db backup writes when --backup-file is absent: ./backups/<name>-<YYYYMMDDTHHMMSSZ>.dump,
+ * returned absolute so the printed path stays correct whatever directory the operator reads it in.
+ */
+export function buildDefaultBackupFilePath(options: {
+  workingDirectoryPath: string
+  projectDatabaseName: ProjectDatabaseName
+  backupInstant?: Date
+}): string {
+  const stamp = formatBackupFileTimestamp(options.backupInstant ?? new Date())
+  return resolve(
+    options.workingDirectoryPath,
+    defaultBackupDirectoryPath,
+    `${options.projectDatabaseName}-${stamp}.dump`,
+  )
+}
+
+/** Compacts an instant to the UTC stamp the default file name carries: 20260827T154500Z, no separators, no milliseconds. */
+function formatBackupFileTimestamp(backupInstant: Date): string {
+  return backupInstant
+    .toISOString()
+    .replaceAll(/[-:]/g, '')
+    .replace(/\.\d+Z$/, 'Z')
+}

package/src/derive-hearthkit-project-name.ts

@@ -0,0 +1,27 @@
+import { hearthkitProjectNameSchema, type HearthkitProjectName } from './cli-contract.ts'
+
+/** What a manifest name becomes when nothing usable survives sanitising, so compose always has a project name. */
+const fallbackHearthkitProjectName = hearthkitProjectNameSchema.parse('hearthkit-app')
+
+/** Compose project names, like the container and volume names built from them, cap at 63 characters. */
+const hearthkitProjectNameLengthLimit = 63
+
+/**
+ * Turns a package.json name into the name compose, containers, and volumes are built from: the
+ * leading @scope/ is dropped, the rest is lowercased, and anything outside [a-z0-9-] becomes a dash.
+ * A result that still cannot be a project name (empty, or not starting with a letter) falls back.
+ */
+export function deriveHearthkitProjectName(manifestName: string | undefined): HearthkitProjectName {
+  if (manifestName === undefined) {
+    return fallbackHearthkitProjectName
+  }
+
+  const sanitized = manifestName
+    .replace(/^@[^/]+\//, '')
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9-]/g, '-')
+    .slice(0, hearthkitProjectNameLengthLimit)
+
+  const parsed = hearthkitProjectNameSchema.safeParse(sanitized)
+  return parsed.success ? parsed.data : fallbackHearthkitProjectName
+}

package/src/derive-local-storage-bucket-name.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest'
+import { loadHearthkitCliBucketExports } from '../test-fixtures/hearthkit-cli-bucket-exports.ts'
+import { hearthkitProjectNameSchema } from './cli-contract.ts'
+
+/** The shortest and longest bucket names the derivation can ever produce, per the contract's totality claim. */
+const shortestPossibleBucketNameLength = 9
+const longestPossibleBucketNameLength = 63
+
+/**
+ * The project names that decide whether the function is total. hearthkitProjectNameSchema is
+ * /^[a-z][a-z0-9-]*$/ with max(63), so a project name may be one character, may end in a hyphen, and
+ * may be 63 characters — and the last case may be 63 characters of which 62 are hyphens.
+ */
+const bucketNameEdgeCases = [
+  {
+    hearthkitProjectName: 'a',
+    expectedBucketName: 'a-uploads',
+    edge: 'the shortest project name the schema accepts',
+  },
+  {
+    hearthkitProjectName: 'my-app-',
+    expectedBucketName: 'my-app-uploads',
+    edge: 'a trailing hyphen, which must not become my-app--uploads',
+  },
+  {
+    hearthkitProjectName: 'a'.repeat(63),
+    expectedBucketName: `${'a'.repeat(55)}-uploads`,
+    edge: 'the longest project name the schema accepts, cut to 55 so the bucket name lands on exactly 63',
+  },
+  {
+    hearthkitProjectName: `a${'-'.repeat(62)}`,
+    expectedBucketName: 'a-uploads',
+    edge: 'truncation leaving nothing but hyphens, which must collapse rather than yield a trailing-hyphen name',
+  },
+] as const
+
+describe('deriveLocalStorageBucketName', () => {
+  it('derives the project-uploads bucket name the generated compose file creates in MinIO', async () => {
+    const { deriveLocalStorageBucketName, localStorageBucketNameSchema } =
+      await loadHearthkitCliBucketExports()
+
+    const localStorageBucketName = deriveLocalStorageBucketName(
+      hearthkitProjectNameSchema.parse('myapp'),
+    )
+
+    expect(localStorageBucketName).toBe('myapp-uploads')
+    expect(localStorageBucketNameSchema.parse(localStorageBucketName)).toBe('myapp-uploads')
+  })
+
+  it.each(bucketNameEdgeCases)(
+    'stays total for a project name that is $edge',
+    async ({ hearthkitProjectName, expectedBucketName }) => {
+      const { deriveLocalStorageBucketName, localStorageBucketNameSchema } =
+        await loadHearthkitCliBucketExports()
+      // Parsing first proves the gate is feeding the function an input the contract really allows,
+      // rather than inventing one the schema would have rejected anyway.
+      const parsedProjectName = hearthkitProjectNameSchema.parse(hearthkitProjectName)
+
+      const localStorageBucketName = deriveLocalStorageBucketName(parsedProjectName)
+
+      expect(localStorageBucketName).toBe(expectedBucketName)
+      // Totality is the reason the function has no failure mode: every accepted project name has to
+      // produce a name localStorageBucketNameSchema accepts, within the 9-to-63 range the contract states.
+      expect(localStorageBucketNameSchema.parse(localStorageBucketName)).toBe(expectedBucketName)
+      expect(localStorageBucketName.length).toBeGreaterThanOrEqual(shortestPossibleBucketNameLength)
+      expect(localStorageBucketName.length).toBeLessThanOrEqual(longestPossibleBucketNameLength)
+    },
+  )
+
+  it('reaches the same project name, and so the same bucket name, the CLI derives from a package.json name', async () => {
+    const {
+      deriveHearthkitProjectName,
+      deriveLocalStorageBucketName,
+      localStorageBucketNameSchema,
+    } = await loadHearthkitCliBucketExports()
+
+    // Promoted to the public surface by this amendment: without it @hearthkit/create cannot reach
+    // the project name the bucket name is built from, so it would re-implement the sanitiser.
+    expect(deriveHearthkitProjectName('@gate/My_App')).toBe('my-app')
+    expect(deriveHearthkitProjectName(undefined)).toBe('hearthkit-app')
+
+    const localStorageBucketName = deriveLocalStorageBucketName(
+      deriveHearthkitProjectName('@gate/My_App'),
+    )
+
+    expect(localStorageBucketName).toBe('my-app-uploads')
+    expect(localStorageBucketNameSchema.parse(localStorageBucketName)).toBe('my-app-uploads')
+  })
+})

package/src/derive-local-storage-bucket-name.ts

@@ -0,0 +1,24 @@
+import { localStorageBucketNameSchema, type DeriveLocalStorageBucketName } from './cli-contract.ts'
+
+/** What every derived bucket name ends in, so a reader of the compose file knows at a glance what the bucket holds. */
+const localStorageBucketNameSuffix = '-uploads'
+
+/** Longest project name that still leaves room for the suffix inside the 63-character bucket name limit. */
+const truncatedProjectNameLengthLimit = 63 - localStorageBucketNameSuffix.length
+
+/**
+ * Derives the bucket name the generated compose file creates in MinIO and @hearthkit/create writes to
+ * STORAGE_BUCKET, so the two cannot drift. Total by construction rather than by validation: the name
+ * is cut to 55 characters and any hyphens left trailing are dropped before the suffix is appended, so
+ * every project name hearthkitProjectNameSchema accepts — one character, ending in a hyphen, or 63
+ * characters of which 62 are hyphens — yields a name localStorageBucketNameSchema accepts.
+ */
+export const deriveLocalStorageBucketName: DeriveLocalStorageBucketName = (
+  hearthkitProjectName,
+) => {
+  const truncated = hearthkitProjectName.slice(0, truncatedProjectNameLengthLimit)
+  const withoutTrailingHyphens = truncated.replace(/-+$/, '')
+  return localStorageBucketNameSchema.parse(
+    `${withoutTrailingHyphens}${localStorageBucketNameSuffix}`,
+  )
+}

package/src/docker-compose-commands.ts

@@ -0,0 +1,100 @@
+import { localInfraServiceNameSchema, type LocalInfraServiceName } from './cli-contract.ts'
+import type { CliRuntimeContext } from './cli-runtime-context.ts'
+import { runChildProcessCommand, type ChildProcessOutcome } from './run-child-process-command.ts'
+
+/** Whether docker can be used at all right now: on PATH and with a daemon that answers. */
+export type DockerAvailability =
+  | { kind: 'docker-available'; serverVersion: string }
+  | { kind: 'docker-unavailable'; detail: string }
+
+/** A wedged daemon should report rather than hang the CLI, so the availability probe is bounded. */
+const dockerProbeTimeoutMilliseconds = 30_000
+
+/** How long docker compose up may spend waiting for services to be running or healthy before it gives up. */
+const composeWaitTimeoutSeconds = 90
+
+/** How much of a failed docker probe's own words to keep when explaining why docker is unusable. */
+const dockerProbeDetailLimit = 400
+
+/**
+ * Probes docker the way the contract defines availability: the executable resolves on the caller's
+ * PATH and `docker info` exits zero. Both halves are one question, because a CLI without a daemon
+ * is just as unusable as no CLI at all.
+ */
+export async function checkDockerAvailability(
+  context: CliRuntimeContext,
+): Promise<DockerAvailability> {
+  const outcome = await runChildProcessCommand({
+    commandName: 'docker',
+    commandArguments: ['info', '--format', '{{.ServerVersion}}'],
+    context,
+    timeoutMilliseconds: dockerProbeTimeoutMilliseconds,
+  })
+
+  if (outcome.kind === 'child-process-not-on-path') {
+    return {
+      kind: 'docker-unavailable',
+      detail: 'docker was not found on PATH; install Docker Desktop or the docker engine',
+    }
+  }
+
+  if (outcome.exitCode !== 0) {
+    return {
+      kind: 'docker-unavailable',
+      detail: `docker info exited ${outcome.exitCode}; the daemon is not running (${outcome.standardError.trim().slice(0, dockerProbeDetailLimit)})`,
+    }
+  }
+
+  return { kind: 'docker-available', serverVersion: outcome.standardOutput.trim() }
+}
+
+/**
+ * Runs one docker compose subcommand against an explicit file, so which compose file is in play is
+ * never guessed from the directory. Compose's stderr is forwarded live because pulls and health
+ * waits are slow enough that silence looks like a hang.
+ */
+export async function runDockerComposeCommand(options: {
+  context: CliRuntimeContext
+  composeFilePath: string
+  composeArguments: readonly string[]
+  forwardStandardError?: boolean
+}): Promise<ChildProcessOutcome> {
+  return runChildProcessCommand({
+    commandName: 'docker',
+    commandArguments: ['compose', '--file', options.composeFilePath, ...options.composeArguments],
+    context: options.context,
+    forwardStandardError: options.forwardStandardError,
+  })
+}
+
+/** The arguments that start every service in the file and wait for it to be running or healthy. */
+export const composeUpArguments = [
+  'up',
+  '--detach',
+  '--wait',
+  '--wait-timeout',
+  String(composeWaitTimeoutSeconds),
+] as const
+
+/** The arguments that stop and remove the file's services while keeping their named volumes. */
+export const composeDownArguments = ['down'] as const
+
+/** The arguments that list the services the file declares, whether or not hearthkit generated it. */
+export const composeServicesArguments = ['config', '--services'] as const
+
+/**
+ * Keeps only the services this package knows how to run. A hand-written compose file naming its own
+ * services therefore reports an empty list even though compose did start them, which is what the
+ * contract says startedInfraServices means.
+ */
+export function readKnownInfraServiceNames(composeServicesOutput: string): LocalInfraServiceName[] {
+  const declaredServiceNames = new Set(
+    composeServicesOutput
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line !== ''),
+  )
+  return localInfraServiceNameSchema.options.filter((serviceName) =>
+    declaredServiceNames.has(serviceName),
+  )
+}

package/src/format-doctor-report.ts

@@ -0,0 +1,25 @@
+import {
+  doctorCheckNameSchema,
+  doctorJsonReportSchema,
+  type DoctorCheckResult,
+  type DoctorJsonReport,
+} from './cli-contract.ts'
+
+/** Width of the name column in the human table; the longest check name plus breathing room. */
+const doctorCheckNameColumnWidth =
+  Math.max(...doctorCheckNameSchema.options.map((checkName) => checkName.length)) + 2
+
+/** The exact JSON envelope doctor --json prints, validated on the way out so the printed text always matches the schema. */
+export function formatDoctorJsonReport(report: DoctorJsonReport): string {
+  return JSON.stringify(doctorJsonReportSchema.parse(report))
+}
+
+/** The human table doctor prints without --json: one line per check, status first so failures are scannable. */
+export function formatDoctorCheckTable(checks: readonly DoctorCheckResult[]): string {
+  return checks
+    .map(
+      (check) =>
+        `${check.status.padEnd(4)}  ${check.checkName.padEnd(doctorCheckNameColumnWidth)}${check.detail}`,
+    )
+    .join('\n')
+}

package/src/generate-local-infra-compose.test.ts

@@ -0,0 +1,215 @@
+import { describe, expect, it } from 'vitest'
+import { loadHearthkitCliBucketExports } from '../test-fixtures/hearthkit-cli-bucket-exports.ts'
+import { loadHearthkitCliEntry } from '../test-fixtures/hearthkit-cli-entry.ts'
+import {
+  generateLocalInfraComposeOptionsSchema,
+  hearthkitProjectNameSchema,
+  localInfraServiceImageByName,
+  localInfraServiceNameSchema,
+} from './cli-contract.ts'
+
+// The function is pure, so a fixed project name is safe: nothing it writes touches the filesystem
+// or the docker daemon, and two gate runs cannot collide.
+const hearthkitProjectName = 'hearthkit-gate-compose'
+
+/** The emitted lines of one service: its key line plus every line indented deeper than it, so a gate can ask what one service does and does not carry. */
+function generatedServiceBlock(composeFileContent: string, serviceName: string): string {
+  const lines = composeFileContent.split('\n')
+  const headerIndex = lines.indexOf(`  ${serviceName}:`)
+  if (headerIndex === -1) {
+    throw new Error(`gate expected the generated compose file to declare a ${serviceName} service`)
+  }
+  const blockLines = [lines[headerIndex] as string]
+  for (const line of lines.slice(headerIndex + 1)) {
+    if (!line.startsWith('    ')) {
+      break
+    }
+    blockLines.push(line)
+  }
+  return blockLines.join('\n')
+}
+
+/** Where a service key sits in the emitted text, so a gate can pin the fixed order the contract calls deterministic. */
+function generatedServiceKeyPosition(composeFileContent: string, serviceName: string): number {
+  const keyPosition = composeFileContent.indexOf(`\n  ${serviceName}:\n`)
+  if (keyPosition === -1) {
+    throw new Error(`gate expected the generated compose file to declare a ${serviceName} service`)
+  }
+  return keyPosition
+}
+
+/** Generates the compose file for one set of services, going through the options schema the contract publishes. */
+async function generateGateComposeFileContent(infraServices: readonly string[]): Promise<string> {
+  const { generateLocalInfraCompose } = await loadHearthkitCliEntry()
+  return generateLocalInfraCompose(
+    generateLocalInfraComposeOptionsSchema.parse({ hearthkitProjectName, infraServices }),
+  )
+}
+
+describe('generateLocalInfraCompose', () => {
+  it('returns identical yaml for identical input and pins every image from localInfraServiceImageByName', async () => {
+    const { generateLocalInfraCompose } = await loadHearthkitCliEntry()
+    const options = generateLocalInfraComposeOptionsSchema.parse({
+      hearthkitProjectName,
+      infraServices: [...localInfraServiceNameSchema.options],
+    })
+
+    const composeFileContent = generateLocalInfraCompose(options)
+    expect(generateLocalInfraCompose(options)).toBe(composeFileContent)
+
+    for (const image of Object.values(localInfraServiceImageByName)) {
+      expect(composeFileContent).toContain(image)
+    }
+    for (const serviceName of localInfraServiceNameSchema.options) {
+      expect(composeFileContent).toContain(`${hearthkitProjectName}-${serviceName}`)
+    }
+    // Host ports are fixed per the contract table.
+    for (const publishedPort of ['5432:5432', '9000:9000', '9001:9001', '1025:1025', '8025:8025']) {
+      expect(composeFileContent).toContain(publishedPort)
+    }
+    // Postgres and minio keep a named volume; mailpit has none.
+    expect(composeFileContent).toContain(`${hearthkitProjectName}-postgres-data`)
+    expect(composeFileContent).toContain(`${hearthkitProjectName}-minio-data`)
+    expect(composeFileContent).not.toContain(`${hearthkitProjectName}-mailpit-data`)
+    // Postgres credentials have to match defaultLocalAdminDatabaseUrl, and the service is health checked.
+    expect(composeFileContent).toContain('POSTGRES_USER')
+    expect(composeFileContent).toContain('POSTGRES_PASSWORD')
+    expect(composeFileContent).toContain('POSTGRES_DB')
+    expect(composeFileContent).toContain('pg_isready')
+    expect(composeFileContent).toContain('MINIO_ROOT_USER')
+    expect(composeFileContent).toContain('MINIO_ROOT_PASSWORD')
+  })
+
+  it('emits the bucket init container immediately after minio and before mailpit, still byte-identical for identical input', async () => {
+    const { localStorageBucketInitServiceName } = await loadHearthkitCliBucketExports()
+    const composeFileContent = await generateGateComposeFileContent([
+      ...localInfraServiceNameSchema.options,
+    ])
+
+    expect(await generateGateComposeFileContent([...localInfraServiceNameSchema.options])).toBe(
+      composeFileContent,
+    )
+    // Fixed order: minio, then the container that creates its bucket, then mailpit. The contract
+    // calls the function deterministic, so the position is part of the output, not an accident.
+    expect(generatedServiceKeyPosition(composeFileContent, 'minio')).toBeLessThan(
+      generatedServiceKeyPosition(composeFileContent, localStorageBucketInitServiceName),
+    )
+    expect(
+      generatedServiceKeyPosition(composeFileContent, localStorageBucketInitServiceName),
+    ).toBeLessThan(generatedServiceKeyPosition(composeFileContent, 'mailpit'))
+    expect(composeFileContent).toContain(
+      `${hearthkitProjectName}-${localStorageBucketInitServiceName}`,
+    )
+    // It is a container the generator adds, never a service a project selects, so it is neither a
+    // LocalInfraServiceName nor an accepted infraServices value.
+    expect(localInfraServiceNameSchema.options as readonly string[]).not.toContain(
+      localStorageBucketInitServiceName,
+    )
+    expect(
+      generateLocalInfraComposeOptionsSchema.safeParse({
+        hearthkitProjectName,
+        infraServices: [localStorageBucketInitServiceName],
+      }).success,
+    ).toBe(false)
+  })
+
+  it('leaves the bucket init container out entirely when minio is not one of the selected services', async () => {
+    const {
+      deriveLocalStorageBucketName,
+      localStorageBucketInitServiceName,
+      localStorageBucketInitImage,
+    } = await loadHearthkitCliBucketExports()
+    const composeFileContent = await generateGateComposeFileContent(['postgres', 'mailpit'])
+
+    expect(composeFileContent).not.toContain(localStorageBucketInitServiceName)
+    expect(composeFileContent).not.toContain(localStorageBucketInitImage)
+    expect(composeFileContent).not.toContain(
+      deriveLocalStorageBucketName(hearthkitProjectNameSchema.parse(hearthkitProjectName)),
+    )
+    expect(composeFileContent).not.toContain('mc mb')
+  })
+
+  it('gives the bucket init container the pinned mc image, a long-syntax wait for a healthy minio, and no restart, ports, volumes or environment', async () => {
+    const { localStorageBucketInitServiceName, localStorageBucketInitImage } =
+      await loadHearthkitCliBucketExports()
+    const composeFileContent = await generateGateComposeFileContent(['minio'])
+    const bucketInitBlock = generatedServiceBlock(
+      composeFileContent,
+      localStorageBucketInitServiceName,
+    )
+
+    // The image comes from its own exported pin, deliberately not from the map of selectable
+    // service images, so the two can be bumped in one place each rather than retyped here.
+    expect(bucketInitBlock).toContain(localStorageBucketInitImage)
+    expect(Object.values(localInfraServiceImageByName) as readonly string[]).not.toContain(
+      localStorageBucketInitImage,
+    )
+    expect(bucketInitBlock).toMatch(
+      new RegExp(
+        `container_name:\\s*['"]?${hearthkitProjectName}-${localStorageBucketInitServiceName}['"]?\\s*$`,
+        'm',
+      ),
+    )
+    // Long syntax, so the container waits for the healthcheck rather than racing the server.
+    expect(bucketInitBlock).toMatch(/depends_on:\s*\n\s+minio:\s*\n\s+condition:\s*service_healthy/)
+    // No restart key, so compose's default no applies; and none of the three blocks the
+    // long-running services carry, because this container publishes and stores nothing. Each is
+    // checked as an absent key rather than an absent word, so the explanatory comment the contract
+    // asks for above this service cannot fail the gate by mentioning one of them.
+    expect(bucketInitBlock).not.toMatch(/^\s+restart:/m)
+    expect(bucketInitBlock).not.toMatch(/^\s+ports:/m)
+    expect(bucketInitBlock).not.toMatch(/^\s+volumes:/m)
+    expect(bucketInitBlock).not.toMatch(/^\s+environment:/m)
+  })
+
+  it('ends the bucket init entrypoint with tail -f /dev/null so the container never exits under docker compose up --wait', async () => {
+    const { deriveLocalStorageBucketName, localStorageBucketInitServiceName } =
+      await loadHearthkitCliBucketExports()
+    const composeFileContent = await generateGateComposeFileContent(['minio'])
+    const bucketInitBlock = generatedServiceBlock(
+      composeFileContent,
+      localStorageBucketInitServiceName,
+    )
+    // The bucket name is taken from the exported derivation rather than retyped, so the name in the
+    // compose file and the name @hearthkit/create writes to STORAGE_BUCKET cannot drift apart.
+    const localStorageBucketName = deriveLocalStorageBucketName(
+      hearthkitProjectNameSchema.parse(hearthkitProjectName),
+    )
+    const bucketInitEntrypointCommand = `mc alias set local http://minio:9000 hearthkit hearthkit && mc mb --ignore-existing local/${localStorageBucketName} && tail -f /dev/null`
+
+    expect(bucketInitBlock).toContain(bucketInitEntrypointCommand)
+    const entrypointPosition = bucketInitBlock.indexOf('entrypoint:')
+    expect(entrypointPosition).toBeGreaterThanOrEqual(0)
+    const entrypointArgumentText = bucketInitBlock.slice(
+      entrypointPosition,
+      bucketInitBlock.indexOf(bucketInitEntrypointCommand),
+    )
+    expect(entrypointArgumentText).toMatch(/['"]sh['"]/)
+    expect(entrypointArgumentText).toMatch(/['"]-c['"]/)
+
+    // tail -f /dev/null is the whole fix and is pinned on its own. docker compose up --wait exits 1
+    // when any service it started has exited, whatever the exit code, and dev infra up always
+    // passes --wait; an init container that did its work and exited 0 would make every dev infra
+    // up report infra-compose-failed with the bucket created perfectly. Nothing may follow it in
+    // the chain, or the container stops being the last thing running.
+    const tailStepPosition = bucketInitBlock.indexOf('tail -f /dev/null')
+    expect(tailStepPosition).toBeGreaterThan(bucketInitBlock.indexOf('mc mb --ignore-existing'))
+    expect(bucketInitBlock.slice(tailStepPosition)).not.toContain('&&')
+    // --ignore-existing is what makes a second dev infra up a no-op instead of a failure.
+    expect(bucketInitBlock).toContain('--ignore-existing')
+  })
+
+  it('health checks the minio service with mc ready local so the bucket init container has a healthy state to wait for', async () => {
+    const composeFileContent = await generateGateComposeFileContent(['minio'])
+    const minioBlock = generatedServiceBlock(composeFileContent, 'minio')
+
+    expect(minioBlock).toContain('healthcheck:')
+    expect(minioBlock).toMatch(
+      /test:\s*\[\s*['"]CMD['"],\s*['"]mc['"],\s*['"]ready['"],\s*['"]local['"]\s*\]/,
+    )
+    // Interval and retry count match the postgres service already in the file.
+    expect(minioBlock).toMatch(/interval:\s*5s/)
+    expect(minioBlock).toMatch(/timeout:\s*5s/)
+    expect(minioBlock).toMatch(/retries:\s*20/)
+  })
+})

package/src/generate-local-infra-compose.ts

@@ -0,0 +1,154 @@
+import {
+  generateLocalInfraComposeOptionsSchema,
+  localInfraServiceImageByName,
+  localInfraServiceNameSchema,
+  localStorageBucketInitImage,
+  localStorageBucketInitServiceName,
+  type GenerateLocalInfraCompose,
+  type HearthkitProjectName,
+  type LocalInfraServiceName,
+} from './cli-contract.ts'
+import { deriveLocalStorageBucketName } from './derive-local-storage-bucket-name.ts'
+
+/** Credentials baked into the generated Postgres and MinIO services; they match defaultLocalAdminDatabaseUrl. */
+const localInfraCredential = 'hearthkit'
+
+/** The address the bucket init container reaches MinIO on: inside the compose network, so it never depends on a published host port. */
+const localStorageServiceEndpoint = 'http://minio:9000'
+
+/** Services whose data survives a compose down, each with one named volume derived from the project name. */
+const volumeBackedServiceNames = [
+  'postgres',
+  'minio',
+] as const satisfies readonly LocalInfraServiceName[]
+
+/**
+ * Builds the local infra compose file. Pure and deterministic: the same options always produce the
+ * same bytes, services are emitted in a fixed order whatever order the caller listed them in, and
+ * every image comes from localInfraServiceImageByName so there is one place to bump a version. The
+ * bucket init container follows minio whenever minio is emitted, and only then.
+ */
+export const generateLocalInfraCompose: GenerateLocalInfraCompose = (options) => {
+  const { hearthkitProjectName, infraServices } =
+    generateLocalInfraComposeOptionsSchema.parse(options)
+  const requestedServiceNames = new Set(infraServices)
+  const emittedServiceNames = localInfraServiceNameSchema.options.filter((serviceName) =>
+    requestedServiceNames.has(serviceName),
+  )
+
+  const serviceBlocks = emittedServiceNames.map((serviceName) =>
+    serviceName === 'minio'
+      ? [
+          ...buildServiceBlock(serviceName, hearthkitProjectName),
+          ...buildBucketInitBlock(hearthkitProjectName),
+        ]
+      : buildServiceBlock(serviceName, hearthkitProjectName),
+  )
+  const volumeNames = volumeBackedServiceNames
+    .filter((serviceName) => requestedServiceNames.has(serviceName))
+    .map((serviceName) => namedVolumeFor(hearthkitProjectName, serviceName))
+
+  const lines = [
+    '# Generated by hearthkit. This file is yours: hearthkit never overwrites an existing docker-compose.yml.',
+    `name: ${hearthkitProjectName}`,
+    '',
+    'services:',
+    ...serviceBlocks.flat(),
+  ]
+
+  if (volumeNames.length > 0) {
+    lines.push('', 'volumes:', ...volumeNames.map((volumeName) => `  ${volumeName}:`))
+  }
+
+  return `${lines.join('\n')}\n`
+}
+
+/** The named volume a service keeps its data in; prefixed with the project so two projects never share one. */
+function namedVolumeFor(
+  hearthkitProjectName: HearthkitProjectName,
+  serviceName: LocalInfraServiceName,
+): string {
+  return `${hearthkitProjectName}-${serviceName}-data`
+}
+
+/** The compose lines for one service, indented ready to sit under the services key. */
+function buildServiceBlock(
+  serviceName: LocalInfraServiceName,
+  hearthkitProjectName: HearthkitProjectName,
+): string[] {
+  const header = [
+    `  ${serviceName}:`,
+    `    image: '${localInfraServiceImageByName[serviceName]}'`,
+    `    container_name: ${hearthkitProjectName}-${serviceName}`,
+    '    restart: unless-stopped',
+  ]
+
+  if (serviceName === 'postgres') {
+    return [
+      ...header,
+      '    environment:',
+      `      POSTGRES_USER: ${localInfraCredential}`,
+      `      POSTGRES_PASSWORD: ${localInfraCredential}`,
+      `      POSTGRES_DB: ${localInfraCredential}`,
+      '    ports:',
+      "      - '5432:5432'",
+      '    volumes:',
+      `      - ${namedVolumeFor(hearthkitProjectName, serviceName)}:/var/lib/postgresql/data`,
+      '    healthcheck:',
+      `      test: ['CMD-SHELL', 'pg_isready -U ${localInfraCredential} -d ${localInfraCredential}']`,
+      '      interval: 5s',
+      '      timeout: 5s',
+      '      retries: 20',
+    ]
+  }
+
+  if (serviceName === 'minio') {
+    return [
+      ...header,
+      "    command: ['server', '/data', '--console-address', ':9001']",
+      '    environment:',
+      `      MINIO_ROOT_USER: ${localInfraCredential}`,
+      `      MINIO_ROOT_PASSWORD: ${localInfraCredential}`,
+      '    ports:',
+      "      - '9000:9000'",
+      "      - '9001:9001'",
+      '    volumes:',
+      `      - ${namedVolumeFor(hearthkitProjectName, serviceName)}:/data`,
+      '    healthcheck:',
+      "      test: ['CMD', 'mc', 'ready', 'local']",
+      '      interval: 5s',
+      '      timeout: 5s',
+      '      retries: 20',
+    ]
+  }
+
+  return [...header, '    ports:', "      - '1025:1025'", "      - '8025:8025'"]
+}
+
+/**
+ * The compose lines for the container that creates the local storage bucket. It carries no restart,
+ * ports, volumes or environment keys on purpose: it publishes and stores nothing, and compose's
+ * default restart policy of no is the right one for a container whose work is already done.
+ */
+function buildBucketInitBlock(hearthkitProjectName: HearthkitProjectName): string[] {
+  const localStorageBucketName = deriveLocalStorageBucketName(hearthkitProjectName)
+  const bucketInitCommand = [
+    `mc alias set local ${localStorageServiceEndpoint} ${localInfraCredential} ${localInfraCredential}`,
+    `mc mb --ignore-existing local/${localStorageBucketName}`,
+    'tail -f /dev/null',
+  ].join(' && ')
+
+  return [
+    '  # Creates the bucket, then idles on purpose. It is not stuck. hearthkit dev infra up always',
+    '  # runs docker compose up --wait. That command fails if a service has exited, whatever its',
+    '  # exit code. Remove the tail -f /dev/null below and every dev infra up fails, even though',
+    '  # the bucket is created. A failed step stops the && chain before tail and exits nonzero.',
+    `  ${localStorageBucketInitServiceName}:`,
+    `    image: '${localStorageBucketInitImage}'`,
+    `    container_name: ${hearthkitProjectName}-${localStorageBucketInitServiceName}`,
+    '    depends_on:',
+    '      minio:',
+    '        condition: service_healthy',
+    `    entrypoint: ['sh', '-c', '${bucketInitCommand}']`,
+  ]
+}