@hearthkit/cli 0.1.0

package/src/resolve-local-infra-compose-file.ts

@@ -0,0 +1,80 @@
+import { access, writeFile } from 'node:fs/promises'
+import { constants as fileSystemConstants } from 'node:fs'
+import { join } from 'node:path'
+import type { CliFailure } from './cli-contract.ts'
+import {
+  composeFileUnwritableFailure,
+  projectManifestMissingFailure,
+} from './cli-failure-results.ts'
+import type { CliRuntimeContext } from './cli-runtime-context.ts'
+import { generateLocalInfraCompose } from './generate-local-infra-compose.ts'
+import { readProjectInfraManifest } from './read-project-infra-manifest.ts'
+
+/** The one compose file name this package reads and, when it is absent, writes. */
+const localInfraComposeFileName = 'docker-compose.yml'
+
+/** Which compose file to run, that none is needed, or why one could not be produced. */
+export type LocalInfraComposeResolution =
+  | { kind: 'local-infra-compose-ready'; composeFilePath: string }
+  | { kind: 'local-infra-compose-not-needed' }
+  | { kind: 'local-infra-compose-rejected'; failure: CliFailure }
+
+/** Where the working directory's compose file lives, whether or not it exists yet. */
+export function localInfraComposeFilePath(context: CliRuntimeContext): string {
+  return join(context.workingDirectoryPath, localInfraComposeFileName)
+}
+
+/** True when the working directory already holds a compose file, which dev infra down needs to know before touching docker. */
+export async function hasLocalInfraComposeFile(context: CliRuntimeContext): Promise<boolean> {
+  try {
+    await access(localInfraComposeFilePath(context), fileSystemConstants.F_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Answers which compose file dev infra up should run. An existing file is used exactly as written
+ * and never overwritten; otherwise the project's manifest decides which services are needed and the
+ * file is generated. A project needing no local infra is a success with nothing written.
+ */
+export async function resolveLocalInfraComposeFile(
+  context: CliRuntimeContext,
+): Promise<LocalInfraComposeResolution> {
+  const composeFilePath = localInfraComposeFilePath(context)
+  if (await hasLocalInfraComposeFile(context)) {
+    return { kind: 'local-infra-compose-ready', composeFilePath }
+  }
+
+  const manifest = await readProjectInfraManifest(context)
+  if (manifest.kind === 'project-infra-manifest-unreadable') {
+    return {
+      kind: 'local-infra-compose-rejected',
+      failure: projectManifestMissingFailure(manifest.manifestPath, manifest.detail),
+    }
+  }
+
+  if (manifest.infraServices.length === 0) {
+    return { kind: 'local-infra-compose-not-needed' }
+  }
+
+  const composeFileContent = generateLocalInfraCompose({
+    hearthkitProjectName: manifest.hearthkitProjectName,
+    infraServices: manifest.infraServices,
+  })
+
+  try {
+    await writeFile(composeFilePath, composeFileContent, 'utf8')
+  } catch (error) {
+    return {
+      kind: 'local-infra-compose-rejected',
+      failure: composeFileUnwritableFailure(
+        composeFilePath,
+        `could not be written (${error instanceof Error ? error.message : String(error)})`,
+      ),
+    }
+  }
+
+  return { kind: 'local-infra-compose-ready', composeFilePath }
+}

package/src/run-child-process-command.ts

@@ -0,0 +1,90 @@
+import { spawn } from 'node:child_process'
+import { writeStandardErrorChunk } from './cli-output-streams.ts'
+import type { CliRuntimeContext } from './cli-runtime-context.ts'
+
+/**
+ * What spawning one external command produced. A binary that is not on PATH is an outcome rather
+ * than an exception, because "docker is not installed" is a named failure mode of this package.
+ */
+export type ChildProcessOutcome =
+  | {
+      kind: 'child-process-exited'
+      exitCode: number
+      standardOutput: string
+      standardError: string
+    }
+  | { kind: 'child-process-not-on-path' }
+
+/** How to run one external command; the binary is named bare so the context's PATH decides which one runs. */
+export type ChildProcessCommandOptions = {
+  commandName: string
+  commandArguments: readonly string[]
+  context: CliRuntimeContext
+  forwardStandardError?: boolean
+  timeoutMilliseconds?: number
+}
+
+/** Long enough for docker to pull an image over a slow link, short enough that a wedged daemon still returns. */
+const defaultChildProcessTimeoutMilliseconds = 600_000
+
+/**
+ * Spawns one external command with the caller's working directory and environment, so PATH lookup
+ * happens against the environment the CLI was given rather than the one this process was started in.
+ * Never rejects: a missing binary and a nonzero exit are both outcomes.
+ */
+export async function runChildProcessCommand(
+  options: ChildProcessCommandOptions,
+): Promise<ChildProcessOutcome> {
+  return new Promise<ChildProcessOutcome>((resolve) => {
+    const child = spawn(options.commandName, [...options.commandArguments], {
+      cwd: options.context.workingDirectoryPath,
+      env: options.context.environmentVariables,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: options.timeoutMilliseconds ?? defaultChildProcessTimeoutMilliseconds,
+    })
+
+    const standardOutputChunks: string[] = []
+    const standardErrorChunks: string[] = []
+    let settled = false
+
+    child.stdout.setEncoding('utf8')
+    child.stdout.on('data', (chunk: string) => standardOutputChunks.push(chunk))
+    child.stderr.setEncoding('utf8')
+    child.stderr.on('data', (chunk: string) => {
+      standardErrorChunks.push(chunk)
+      if (options.forwardStandardError === true) {
+        writeStandardErrorChunk(chunk)
+      }
+    })
+
+    child.on('error', (error: NodeJS.ErrnoException) => {
+      if (settled) {
+        return
+      }
+      settled = true
+      if (error.code === 'ENOENT') {
+        resolve({ kind: 'child-process-not-on-path' })
+        return
+      }
+      resolve({
+        kind: 'child-process-exited',
+        exitCode: 1,
+        standardOutput: standardOutputChunks.join(''),
+        standardError: `${standardErrorChunks.join('')}${error.message}`,
+      })
+    })
+
+    child.on('close', (exitCode) => {
+      if (settled) {
+        return
+      }
+      settled = true
+      resolve({
+        kind: 'child-process-exited',
+        exitCode: exitCode ?? 1,
+        standardOutput: standardOutputChunks.join(''),
+        standardError: standardErrorChunks.join(''),
+      })
+    })
+  })
+}

package/src/run-db-lifecycle-command.ts

@@ -0,0 +1,103 @@
+import { resolve } from 'node:path'
+import {
+  backupProjectDatabase,
+  createProjectDatabase,
+  dropProjectDatabase,
+  restoreProjectDatabase,
+  runDatabaseMigrations,
+} from '@hearthkit/db'
+import type { CliCommandInvocation, CliCommandResult } from './cli-contract.ts'
+import { dbCommandFailedFailure } from './cli-failure-results.ts'
+import type { CliRuntimeContext } from './cli-runtime-context.ts'
+
+/** The five invocations that are only a thin call into @hearthkit/db; no database logic lives in this package. */
+export type DbLifecycleInvocation = Extract<
+  CliCommandInvocation,
+  { commandPath: 'db create' | 'db drop' | 'db migrate' | 'db backup' | 'db restore' }
+>
+
+/**
+ * Runs one db command through @hearthkit/db and translates its result. Any DbFailure is carried out
+ * verbatim, so the underlying message and its prefix reach the operator unchanged. Paths given on
+ * the command line are reported exactly as typed but resolved against the working directory first.
+ */
+export async function runDbLifecycleCommand(options: {
+  invocation: DbLifecycleInvocation
+  context: CliRuntimeContext
+}): Promise<CliCommandResult> {
+  const { invocation, context } = options
+
+  if (invocation.commandPath === 'db create') {
+    const result = await createProjectDatabase({
+      adminDatabaseUrl: invocation.adminDatabaseUrl,
+      projectDatabaseName: invocation.projectDatabaseName,
+    })
+    if (result.kind !== 'project-database-created') {
+      return dbCommandFailedFailure(result)
+    }
+    return {
+      kind: 'db-create-command-succeeded',
+      projectDatabaseName: result.projectDatabaseName,
+      connectionString: result.connectionString,
+    }
+  }
+
+  if (invocation.commandPath === 'db drop') {
+    const result = await dropProjectDatabase({
+      adminDatabaseUrl: invocation.adminDatabaseUrl,
+      projectDatabaseName: invocation.projectDatabaseName,
+    })
+    if (result.kind !== 'project-database-dropped') {
+      return dbCommandFailedFailure(result)
+    }
+    return {
+      kind: 'db-drop-command-succeeded',
+      projectDatabaseName: result.projectDatabaseName,
+    }
+  }
+
+  if (invocation.commandPath === 'db migrate') {
+    const result = await runDatabaseMigrations({
+      databaseUrl: invocation.databaseUrl,
+      migrationsFolderPath: resolve(context.workingDirectoryPath, invocation.migrationsFolderPath),
+    })
+    if (result.kind !== 'database-migrations-applied') {
+      return dbCommandFailedFailure(result)
+    }
+    return {
+      kind: 'db-migrate-command-succeeded',
+      appliedMigrationCount: result.appliedMigrationCount,
+    }
+  }
+
+  if (invocation.commandPath === 'db backup') {
+    const result = await backupProjectDatabase({
+      adminDatabaseUrl: invocation.adminDatabaseUrl,
+      projectDatabaseName: invocation.projectDatabaseName,
+      backupFilePath: resolve(context.workingDirectoryPath, invocation.backupFilePath),
+    })
+    if (result.kind !== 'project-database-backed-up') {
+      return dbCommandFailedFailure(result)
+    }
+    return {
+      kind: 'db-backup-command-succeeded',
+      projectDatabaseName: result.projectDatabaseName,
+      backupFilePath: invocation.backupFilePath,
+      backupByteCount: result.backupByteCount,
+    }
+  }
+
+  const result = await restoreProjectDatabase({
+    adminDatabaseUrl: invocation.adminDatabaseUrl,
+    projectDatabaseName: invocation.projectDatabaseName,
+    backupFilePath: resolve(context.workingDirectoryPath, invocation.backupFilePath),
+  })
+  if (result.kind !== 'project-database-restored') {
+    return dbCommandFailedFailure(result)
+  }
+  return {
+    kind: 'db-restore-command-succeeded',
+    projectDatabaseName: result.projectDatabaseName,
+    backupFilePath: invocation.backupFilePath,
+  }
+}

package/src/run-dev-command.ts

@@ -0,0 +1,104 @@
+import { spawn } from 'node:child_process'
+import { access } from 'node:fs/promises'
+import { constants as fileSystemConstants } from 'node:fs'
+import { constants as osConstants } from 'node:os'
+import { join } from 'node:path'
+import { cliDevInfraUpCompleteLinePrefix, type CliCommandResult } from './cli-contract.ts'
+import { nextDevUnavailableFailure } from './cli-failure-results.ts'
+import { writeStandardErrorLine } from './cli-output-streams.ts'
+import type { CliRuntimeContext } from './cli-runtime-context.ts'
+import { runDevInfraUpCommand } from './run-dev-infra-command.ts'
+
+/** The project's own Next.js binary; hearthkit never installs or bundles one of its own. */
+const projectNextBinaryRelativePath = join('node_modules', '.bin', 'next')
+
+/** The exit code range a process may report; a child killed by a signal is folded into it as 128 + signal. */
+const maximumProcessExitCode = 255
+
+/** How the next dev child ended, or why it could not be started at all. */
+type NextDevOutcome =
+  | { kind: 'next-dev-exited'; nextDevExitCode: number }
+  | { kind: 'next-dev-not-spawnable'; detail: string }
+
+/**
+ * Brings local infra up and then hands the terminal to the project's own next dev, whose stdio is
+ * inherited rather than captured so Next's interactive output behaves exactly as it does directly.
+ * The command's exit code is the child's, which is why it is not always 0, 1, or 2.
+ */
+export async function runDevCommand(context: CliRuntimeContext): Promise<CliCommandResult> {
+  const infraResult = await runDevInfraUpCommand(context)
+  if (infraResult.kind !== 'dev-infra-up-succeeded') {
+    return infraResult
+  }
+
+  // Progress, not machine-readable output: stdout belongs to next dev from here on.
+  writeStandardErrorLine(
+    `${cliDevInfraUpCompleteLinePrefix} ${describeStartedServices(infraResult.startedInfraServices)}`,
+  )
+
+  const nextBinaryPath = join(context.workingDirectoryPath, projectNextBinaryRelativePath)
+  try {
+    await access(nextBinaryPath, fileSystemConstants.X_OK)
+  } catch {
+    return nextDevUnavailableFailure(
+      `no runnable next binary at ${nextBinaryPath}; install next in this project first`,
+    )
+  }
+
+  const outcome = await runNextDevProcess(nextBinaryPath, context)
+  if (outcome.kind === 'next-dev-not-spawnable') {
+    return nextDevUnavailableFailure(`${nextBinaryPath} could not be started (${outcome.detail})`)
+  }
+
+  return { kind: 'dev-command-exited', nextDevExitCode: outcome.nextDevExitCode }
+}
+
+/** Names the started services for the progress line, or says plainly that none were needed. */
+function describeStartedServices(startedInfraServices: readonly string[]): string {
+  return startedInfraServices.length === 0
+    ? 'no local infra services needed'
+    : `started ${startedInfraServices.join(', ')}`
+}
+
+/** Runs next dev to completion with inherited stdio and reports the code the shell would have seen. */
+async function runNextDevProcess(
+  nextBinaryPath: string,
+  context: CliRuntimeContext,
+): Promise<NextDevOutcome> {
+  return new Promise<NextDevOutcome>((resolve) => {
+    const child = spawn(nextBinaryPath, ['dev'], {
+      cwd: context.workingDirectoryPath,
+      env: context.environmentVariables,
+      stdio: 'inherit',
+    })
+
+    let settled = false
+
+    child.on('error', (error: Error) => {
+      if (settled) {
+        return
+      }
+      settled = true
+      resolve({ kind: 'next-dev-not-spawnable', detail: error.message })
+    })
+
+    child.on('close', (exitCode, signal) => {
+      if (settled) {
+        return
+      }
+      settled = true
+      resolve({ kind: 'next-dev-exited', nextDevExitCode: readChildExitCode(exitCode, signal) })
+    })
+  })
+}
+
+/** Folds an exit code or terminating signal into the 0 to 255 range the contract allows. */
+function readChildExitCode(exitCode: number | null, signal: NodeJS.Signals | null): number {
+  if (exitCode !== null) {
+    return Math.min(maximumProcessExitCode, Math.max(0, exitCode))
+  }
+  if (signal !== null) {
+    return Math.min(maximumProcessExitCode, 128 + (osConstants.signals[signal] ?? 0))
+  }
+  return 1
+}

package/src/run-dev-infra-command.ts

@@ -0,0 +1,115 @@
+import type { CliCommandResult, CliFailure } from './cli-contract.ts'
+import { dockerUnavailableFailure, infraComposeFailedFailure } from './cli-failure-results.ts'
+import type { CliRuntimeContext } from './cli-runtime-context.ts'
+import {
+  checkDockerAvailability,
+  composeDownArguments,
+  composeServicesArguments,
+  composeUpArguments,
+  readKnownInfraServiceNames,
+  runDockerComposeCommand,
+} from './docker-compose-commands.ts'
+import type { ChildProcessOutcome } from './run-child-process-command.ts'
+import {
+  hasLocalInfraComposeFile,
+  localInfraComposeFilePath,
+  resolveLocalInfraComposeFile,
+} from './resolve-local-infra-compose-file.ts'
+
+/**
+ * Starts the project's local infra. Docker is checked before anything is read or written, then the
+ * compose file is resolved (used as found, or generated from package.json), then compose runs. A
+ * project that needs no local services succeeds having started nothing and written nothing.
+ */
+export async function runDevInfraUpCommand(context: CliRuntimeContext): Promise<CliCommandResult> {
+  const availability = await checkDockerAvailability(context)
+  if (availability.kind === 'docker-unavailable') {
+    return dockerUnavailableFailure(availability.detail)
+  }
+
+  const resolution = await resolveLocalInfraComposeFile(context)
+  if (resolution.kind === 'local-infra-compose-rejected') {
+    return resolution.failure
+  }
+  if (resolution.kind === 'local-infra-compose-not-needed') {
+    return { kind: 'dev-infra-up-succeeded', startedInfraServices: [] }
+  }
+
+  const upOutcome = await runDockerComposeCommand({
+    context,
+    composeFilePath: resolution.composeFilePath,
+    composeArguments: composeUpArguments,
+    forwardStandardError: true,
+  })
+  const upFailure = readComposeCommandFailure(upOutcome, composeUpArguments)
+  if (upFailure !== undefined) {
+    return upFailure
+  }
+
+  const servicesOutcome = await runDockerComposeCommand({
+    context,
+    composeFilePath: resolution.composeFilePath,
+    composeArguments: composeServicesArguments,
+  })
+  const servicesFailure = readComposeCommandFailure(servicesOutcome, composeServicesArguments)
+  if (servicesFailure !== undefined) {
+    return servicesFailure
+  }
+
+  return {
+    kind: 'dev-infra-up-succeeded',
+    startedInfraServices:
+      servicesOutcome.kind === 'child-process-exited'
+        ? readKnownInfraServiceNames(servicesOutcome.standardOutput)
+        : [],
+  }
+}
+
+/**
+ * Stops the project's local infra, keeping named volumes so data survives. A working directory with
+ * no compose file has nothing to stop, and that is a success that never needs docker at all.
+ */
+export async function runDevInfraDownCommand(
+  context: CliRuntimeContext,
+): Promise<CliCommandResult> {
+  if (!(await hasLocalInfraComposeFile(context))) {
+    return { kind: 'dev-infra-down-succeeded' }
+  }
+
+  const availability = await checkDockerAvailability(context)
+  if (availability.kind === 'docker-unavailable') {
+    return dockerUnavailableFailure(availability.detail)
+  }
+
+  const downOutcome = await runDockerComposeCommand({
+    context,
+    composeFilePath: localInfraComposeFilePath(context),
+    composeArguments: composeDownArguments,
+    forwardStandardError: true,
+  })
+  const downFailure = readComposeCommandFailure(downOutcome, composeDownArguments)
+  if (downFailure !== undefined) {
+    return downFailure
+  }
+
+  return { kind: 'dev-infra-down-succeeded' }
+}
+
+/** Turns a compose invocation that did not work into the matching failure, or undefined when it did. */
+function readComposeCommandFailure(
+  outcome: ChildProcessOutcome,
+  composeArguments: readonly string[],
+): CliFailure | undefined {
+  if (outcome.kind === 'child-process-not-on-path') {
+    return dockerUnavailableFailure('docker left PATH between the availability check and this call')
+  }
+  if (outcome.exitCode !== 0) {
+    return infraComposeFailedFailure({
+      composeArguments,
+      composeExitCode: outcome.exitCode,
+      composeStandardError:
+        outcome.standardError.trim() === '' ? outcome.standardOutput : outcome.standardError,
+    })
+  }
+  return undefined
+}