@hearthkit/cli 0.1.0

package/src/hearthkit-bin-entry.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// The `hearthkit` bin, and plain JavaScript for the reason spelled out in full in
+// @hearthkit/config's `src/register-node-modules-type-stripping.js`: Node 24.20.0 refuses to strip
+// types from a `.ts` file under `node_modules`, so the bin an installed project runs cannot itself
+// be TypeScript. The hook lives in @hearthkit/config, which this package declares as a direct
+// dependency for exactly this import, so there is one copy of it rather than one per entry point.
+//
+// `hearthkit-bin.ts` is reached by a dynamic import, and that is load-bearing rather than a style
+// choice. Node loads the source of an entire static module graph before it evaluates any of it, so
+// a static `import './hearthkit-bin.ts'` would be read off disk while the hook module below is
+// still unevaluated, and would throw ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING. The dynamic
+// import runs after this module body, by which time the hook is registered.
+//
+// API reference checked against the current Node 24 docs on 2026-09-07:
+// https://nodejs.org/docs/latest-v24.x/api/module.html
+
+import '@hearthkit/config/register-node-modules-type-stripping'
+
+await import('./hearthkit-bin.ts')

package/src/hearthkit-bin-execution.test.ts

@@ -0,0 +1,136 @@
+import { spawn } from 'node:child_process'
+import { access, readFile } from 'node:fs/promises'
+import { constants } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+import { afterAll, describe, expect, it } from 'vitest'
+import {
+  createGateDirectory,
+  gateEnvironment,
+  removeGateDirectory,
+} from '../test-fixtures/gate-project-directories.ts'
+import { cliDevInfraDownCompleteLinePrefix, cliUsageErrorPrefix } from './cli-contract.ts'
+
+const packageDirectoryPath = dirname(dirname(fileURLToPath(import.meta.url)))
+const directoriesToRemove: string[] = []
+
+afterAll(async () => {
+  for (const directoryPath of directoriesToRemove) {
+    await removeGateDirectory(directoryPath)
+  }
+})
+
+/**
+ * The path package.json advertises as the hearthkit binary, resolved from the bin field rather than
+ * hardcoded, so this gate fails when the bin wiring drifts instead of testing a file nobody installs.
+ */
+async function resolveAdvertisedBinPath(): Promise<string> {
+  const manifest: unknown = JSON.parse(
+    await readFile(resolve(packageDirectoryPath, 'package.json'), 'utf8'),
+  )
+  const binField =
+    typeof manifest === 'object' && manifest !== null && 'bin' in manifest
+      ? manifest.bin
+      : undefined
+  const advertisedBinEntry =
+    typeof binField === 'object' && binField !== null && 'hearthkit' in binField
+      ? binField.hearthkit
+      : undefined
+  if (typeof advertisedBinEntry !== 'string') {
+    throw new Error(
+      `gate expected packages/cli/package.json to declare bin.hearthkit as a path string, received ${JSON.stringify(binField)}`,
+    )
+  }
+  const binPath = resolve(packageDirectoryPath, advertisedBinEntry)
+  await access(binPath, constants.X_OK).catch(() => {
+    throw new Error(
+      `gate expected the advertised bin ${advertisedBinEntry} to exist and be executable at ${binPath}`,
+    )
+  })
+  return binPath
+}
+
+/** Runs one command as a real child process and reports only what an operator sees: exit code and the two streams. */
+async function spawnCliProcess(options: {
+  command: string
+  commandArguments: string[]
+  cwd: string
+}): Promise<{ exitCode: number; standardOutput: string; standardError: string }> {
+  return new Promise((resolveResult, rejectResult) => {
+    const child = spawn(options.command, options.commandArguments, {
+      cwd: options.cwd,
+      env: gateEnvironment(),
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    const standardOutputChunks: string[] = []
+    const standardErrorChunks: string[] = []
+    child.stdout.on('data', (chunk: Buffer) => standardOutputChunks.push(chunk.toString('utf8')))
+    child.stderr.on('data', (chunk: Buffer) => standardErrorChunks.push(chunk.toString('utf8')))
+    child.on('error', (error) =>
+      rejectResult(
+        new Error(`gate could not spawn ${options.command}: ${error.message}`, { cause: error }),
+      ),
+    )
+    child.on('close', (code, signal) => {
+      if (code === null) {
+        rejectResult(new Error(`gate expected an exit code, the process was killed by ${signal}`))
+        return
+      }
+      resolveResult({
+        exitCode: code,
+        standardOutput: standardOutputChunks.join(''),
+        standardError: standardErrorChunks.join(''),
+      })
+    })
+  })
+}
+
+/** The non-empty lines of a stream, so a gate can name the one line it expects without matching whitespace. */
+function nonEmptyLines(streamText: string): string[] {
+  return streamText.split('\n').filter((line) => line.trim().length > 0)
+}
+
+// These two gates are the only place the binary itself is exercised: every other CLI gate calls
+// runHearthkitCli in process, which cannot catch a broken bin field, a missing executable bit or an
+// exit code the wrapper failed to propagate.
+describe('the hearthkit binary as a child process', () => {
+  it('runs through its own shebang and exits 0 on the dev infra down no-op', async () => {
+    const binPath = await resolveAdvertisedBinPath()
+    const directoryPath = await createGateDirectory('bin-exit-zero')
+    directoriesToRemove.push(directoryPath)
+
+    // Executed directly, with no interpreter in front of it: this holds the shebang and the
+    // executable bit, which is what makes the file runnable once a package manager links it.
+    const run = await spawnCliProcess({
+      command: binPath,
+      commandArguments: ['dev', 'infra', 'down'],
+      cwd: directoryPath,
+    })
+
+    expect(run.exitCode).toBe(0)
+    expect(nonEmptyLines(run.standardError)).toEqual([])
+    const printedLines = nonEmptyLines(run.standardOutput)
+    expect(printedLines).toHaveLength(1)
+    expect(printedLines[0]?.startsWith(cliDevInfraDownCompleteLinePrefix)).toBe(true)
+  })
+
+  it('exits 2 with the usage prefix on stderr when the command path is unknown', async () => {
+    const binPath = await resolveAdvertisedBinPath()
+    const directoryPath = await createGateDirectory('bin-exit-two')
+    directoriesToRemove.push(directoryPath)
+
+    // Invoked as node <bin>, the way a package manager bin shim reads the shebang and calls the
+    // interpreter, so both entry routes into the same wrapper are covered by this file.
+    const run = await spawnCliProcess({
+      command: process.execPath,
+      commandArguments: [binPath, 'db', 'frobnicate'],
+      cwd: directoryPath,
+    })
+
+    expect(run.exitCode).toBe(2)
+    expect(nonEmptyLines(run.standardOutput)).toEqual([])
+    const reportedLines = nonEmptyLines(run.standardError)
+    const lastReportedLine = reportedLines.at(-1)
+    expect(lastReportedLine?.startsWith(cliUsageErrorPrefix)).toBe(true)
+  })
+})

package/src/hearthkit-bin.ts

@@ -0,0 +1,8 @@
+// The hearthkit command itself. Reached through hearthkit-bin-entry.js, never named in the bin
+// field directly, because Node refuses to strip types from a .ts file under node_modules and the
+// entry shim is what installs the loader hook that does it. The relative imports below name .ts
+// files because that is what actually ships: there is still no build step.
+import { runHearthkitCli } from './run-hearthkit-cli.ts'
+
+const { exitCode } = await runHearthkitCli({ argv: process.argv.slice(2) })
+process.exitCode = exitCode

package/src/index.ts

@@ -0,0 +1,107 @@
+/** Public entry point of @hearthkit/cli: a named re-export of exactly the surface the contract lists, so no internal module is importable by consumers. */
+
+/** Runs one hearthkit command and returns its exit code and structured result; the bin is a wrapper around this. */
+export { runHearthkitCli } from './run-hearthkit-cli.ts'
+
+/** Builds the local infra compose file; pure, so the scaffolder can reuse it instead of copying a template. */
+export { generateLocalInfraCompose } from './generate-local-infra-compose.ts'
+
+/** Derives the bucket name the generated compose file creates in MinIO; pure and total, so the scaffolder writes the identical string to STORAGE_BUCKET. */
+export { deriveLocalStorageBucketName } from './derive-local-storage-bucket-name.ts'
+
+/** Turns a package.json name into the project name compose, container, volume, and bucket names are built from; falls back to hearthkit-app. */
+export { deriveHearthkitProjectName } from './derive-hearthkit-project-name.ts'
+
+/** Contract values: the unique literal prefix every failure message starts with. */
+export {
+  cliAdminUrlInvalidErrorPrefix,
+  cliComposeFileUnwritableErrorPrefix,
+  cliDatabaseUrlInvalidErrorPrefix,
+  cliDatabaseUrlMissingErrorPrefix,
+  cliDockerUnavailableErrorPrefix,
+  cliDoctorFailedErrorPrefix,
+  cliInfraComposeFailedErrorPrefix,
+  cliNextDevUnavailableErrorPrefix,
+  cliPaymentsCatalogNotFoundErrorPrefix,
+  cliPaymentsCatalogUnloadableErrorPrefix,
+  cliPaymentsSyncFailedErrorPrefix,
+  cliProjectManifestMissingErrorPrefix,
+  cliUsageErrorPrefix,
+} from './cli-contract.ts'
+
+/** Contract values: the unique literal prefix of each command's single stdout line and of the db create warning. */
+export {
+  cliDbBackupCompleteLinePrefix,
+  cliDbCreateCredentialsWarningPrefix,
+  cliDbDropCompleteLinePrefix,
+  cliDbMigrateCompleteLinePrefix,
+  cliDbRestoreCompleteLinePrefix,
+  cliDevInfraDownCompleteLinePrefix,
+  cliDevInfraUpCompleteLinePrefix,
+  cliPaymentsSyncCompleteLinePrefix,
+} from './cli-contract.ts'
+
+/** Contract values: this package's env fragment, the defaults its resolution rules fall back to, and the catalog vocabulary payments sync reads. */
+export {
+  adminDatabaseUrlEnvVariableName,
+  cliEnvSchemaFragment,
+  defaultBackupDirectoryPath,
+  defaultLocalAdminDatabaseUrl,
+  defaultMigrationsFolderPath,
+  defaultPaymentsCatalogPath,
+  paymentsCatalogModuleExportName,
+  stripeSecretKeyEnvVariableName,
+} from './cli-contract.ts'
+
+/** Contract values: the local infra vocabulary, including the single place each service image is pinned. */
+export {
+  generateLocalInfraComposeOptionsSchema,
+  hearthkitProjectNameSchema,
+  localInfraServiceImageByName,
+  localInfraServiceNameSchema,
+  localInfraServicesByHearthkitPackage,
+} from './cli-contract.ts'
+
+/** Contract values: the bucket init container's service key and image pin, and the name schema the derived bucket name satisfies. */
+export {
+  localStorageBucketInitImage,
+  localStorageBucketInitServiceName,
+  localStorageBucketNameSchema,
+} from './cli-contract.ts'
+
+/** Contract values: the command registry, result, failure, and doctor schemas gates and consumers parse with. */
+export {
+  cliCommandInvocationSchema,
+  cliCommandPathSchema,
+  cliCommandResultSchema,
+  cliCommandSuccessSchema,
+  cliExitCodeSchema,
+  cliFailureSchema,
+  cliRunOutcomeSchema,
+  doctorCheckNameSchema,
+  doctorCheckResultSchema,
+  doctorJsonReportSchema,
+  runHearthkitCliOptionsSchema,
+} from './cli-contract.ts'
+
+/** Contract types: the vocabulary a consumer needs to hold a run's outcome without re-deriving it. */
+export type {
+  CliCommandInvocation,
+  CliCommandPath,
+  CliCommandResult,
+  CliCommandSuccess,
+  CliExitCode,
+  CliFailure,
+  CliRunOutcome,
+  DeriveLocalStorageBucketName,
+  DoctorCheckName,
+  DoctorCheckResult,
+  DoctorJsonReport,
+  GenerateLocalInfraCompose,
+  GenerateLocalInfraComposeOptions,
+  HearthkitProjectName,
+  LocalInfraServiceName,
+  LocalStorageBucketName,
+  RunHearthkitCli,
+  RunHearthkitCliOptions,
+} from './cli-contract.ts'

package/src/load-payments-catalog-module.ts

@@ -0,0 +1,60 @@
+import { stat } from 'node:fs/promises'
+import { pathToFileURL } from 'node:url'
+import { paymentsCatalogModuleExportName } from './cli-contract.ts'
+
+/**
+ * Reads the project's catalog module off disk without validating what it exports.
+ *
+ * Node 24 strips types natively, so a `.ts` catalog needs no build step, and the file's own
+ * `@hearthkit/payments` import resolves from the project's `node_modules` rather than from this
+ * package. The exported value travels on as `unknown` on purpose: `createPaymentsClient` is what
+ * validates a catalog, so a bad shape comes back as the payments failure rather than as a CLI one.
+ */
+
+/** What loading one catalog module came to; the two failing branches carry the detail the CLI reports. */
+export type PaymentsCatalogModuleLoad =
+  | { kind: 'payments-catalog-loaded'; catalogValue: unknown }
+  | { kind: 'payments-catalog-file-absent' }
+  | { kind: 'payments-catalog-unloadable'; loadFailureDetail: string }
+
+/** True when a readable file sits at the path; a directory is treated as no catalog at all. */
+async function catalogFileExists(catalogPath: string): Promise<boolean> {
+  return stat(catalogPath).then(
+    (entry) => entry.isFile(),
+    () => false,
+  )
+}
+
+/** Imports the catalog module at an absolute path and reads appPaymentsCatalog, falling back to the default export. */
+export async function loadPaymentsCatalogModule(
+  catalogPath: string,
+): Promise<PaymentsCatalogModuleLoad> {
+  if (!(await catalogFileExists(catalogPath))) {
+    return { kind: 'payments-catalog-file-absent' }
+  }
+
+  let catalogModule: Record<string, unknown>
+  try {
+    catalogModule = await import(pathToFileURL(catalogPath).href)
+  } catch (thrownValue) {
+    return {
+      kind: 'payments-catalog-unloadable',
+      loadFailureDetail: thrownValue instanceof Error ? thrownValue.message : String(thrownValue),
+    }
+  }
+
+  const namedExport = catalogModule[paymentsCatalogModuleExportName]
+  if (namedExport !== undefined) {
+    return { kind: 'payments-catalog-loaded', catalogValue: namedExport }
+  }
+
+  const defaultExport = catalogModule.default
+  if (defaultExport !== undefined) {
+    return { kind: 'payments-catalog-loaded', catalogValue: defaultExport }
+  }
+
+  return {
+    kind: 'payments-catalog-unloadable',
+    loadFailureDetail: `the module exports neither ${paymentsCatalogModuleExportName} nor a default export`,
+  }
+}