@hearthkit/cli 0.1.0

package/src/run-hearthkit-cli-payments-sync.test.ts

@@ -0,0 +1,180 @@
+import { isAbsolute, resolve } from 'node:path'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import {
+  expectCliFailure,
+  expectCliSuccess,
+  runHearthkitCliGate,
+  singleStandardOutputLine,
+} from '../test-fixtures/cli-run-expectations.ts'
+import {
+  createGateDirectory,
+  removeGateDirectory,
+} from '../test-fixtures/gate-project-directories.ts'
+import { loadHearthkitCliPaymentsExports } from '../test-fixtures/hearthkit-cli-payments-exports.ts'
+import {
+  uniqueGateCliCatalogNames,
+  writeGateCliCatalogFile,
+  writeGateCliUnusableCatalogFile,
+  type GateCliCatalogNames,
+} from '../test-fixtures/payments-sync-gate-catalog.ts'
+import {
+  archiveGateStripeSyncedPrices,
+  assertGateStripeSyncWasTestMode,
+  readGateStripeSecretKey,
+} from '../test-fixtures/stripe-gate-secret-key.ts'
+
+/**
+ * hearthkit payments sync. One live gate against Stripe test mode, and the three file and
+ * environment paths that reach no service at all.
+ *
+ * The command is specified to read exactly one environment variable, so every gate here hands it an
+ * environment holding only that variable or nothing. It opens no Postgres connection either — the
+ * CLI builds the payments client with a database URL nothing listens on — so a sync that started
+ * querying would fail these gates rather than pass them.
+ */
+
+/** Prices this run created in the shared test-mode Stripe account, archived in afterAll. */
+const createdStripePrices: { stripePriceId: unknown; stripeProductId: unknown }[] = []
+
+let gateDirectoryPath: string
+let liveCatalogNames: GateCliCatalogNames
+let gateStripeSecretKey: string | undefined
+
+beforeAll(async () => {
+  gateDirectoryPath = await createGateDirectory('payments-sync')
+  liveCatalogNames = uniqueGateCliCatalogNames('sync')
+})
+
+afterAll(async () => {
+  if (gateStripeSecretKey !== undefined && createdStripePrices.length > 0) {
+    await archiveGateStripeSyncedPrices(gateStripeSecretKey, createdStripePrices)
+  }
+  await removeGateDirectory(gateDirectoryPath)
+})
+
+describe('hearthkit payments sync', () => {
+  it('pushes the project catalog to Stripe test mode and reports one created price per catalog price', async () => {
+    const { cliPaymentsSyncCompleteLinePrefix, defaultPaymentsCatalogPath } =
+      await loadHearthkitCliPaymentsExports()
+    // Not skipped when the key is absent: this is the only gate that proves the command reaches
+    // Stripe at all, so a missing key has to fail loudly. The helper names both places to put it.
+    gateStripeSecretKey = await readGateStripeSecretKey()
+    const catalogFilePath = await writeGateCliCatalogFile({
+      directoryPath: gateDirectoryPath,
+      fileName: 'payments-catalog.ts',
+      catalogNames: liveCatalogNames,
+    })
+
+    const run = await runHearthkitCliGate({
+      argv: ['payments', 'sync'],
+      cwd: gateDirectoryPath,
+      // Only STRIPE_SECRET_KEY, because the contract says the command reads nothing else.
+      env: { STRIPE_SECRET_KEY: gateStripeSecretKey },
+    })
+
+    const success = expectCliSuccess(run, 'payments-sync-command-succeeded', 0)
+    // The measured test-mode guard, before this run's objects are touched again for any reason.
+    assertGateStripeSyncWasTestMode(success.stripeLivemode)
+    expect(success.stripeLivemode).toBe(false)
+    createdStripePrices.push(...success.syncedPrices)
+
+    // No --catalog flag, so the path is the default resolved against cwd.
+    expect(success.catalogPath).toBe(resolve(gateDirectoryPath, defaultPaymentsCatalogPath))
+    expect(success.catalogPath).toBe(catalogFilePath)
+    expect([...success.syncedPrices].map((price) => String(price.priceName)).toSorted()).toEqual(
+      [liveCatalogNames.subscriptionPriceName, liveCatalogNames.oneTimePriceName].toSorted(),
+    )
+    // Every price name is unique to this run, so the first sync of it can only create.
+    expect(success.syncedPrices.every((price) => price.syncAction === 'created')).toBe(true)
+    expect(success.createdPriceCount).toBe(success.syncedPrices.length)
+    expect(success.replacedPriceCount).toBe(0)
+    expect(success.unchangedPriceCount).toBe(0)
+    expect(
+      success.createdPriceCount + success.replacedPriceCount + success.unchangedPriceCount,
+    ).toBe(success.syncedPrices.length)
+
+    // One machine-readable line on stdout; only its prefix and the counts it carries are contract.
+    const printedLine = singleStandardOutputLine(run)
+    expect(printedLine.startsWith(cliPaymentsSyncCompleteLinePrefix)).toBe(true)
+    expect(printedLine).toContain(String(success.createdPriceCount))
+  })
+
+  it('fails with cli-payments-catalog-not-found and the absolute default path when the project has no catalog file', async () => {
+    const { cliPaymentsCatalogNotFoundErrorPrefix, defaultPaymentsCatalogPath } =
+      await loadHearthkitCliPaymentsExports()
+    // A directory of its own, so the live gate's catalog file cannot make this one pass.
+    const emptyDirectoryPath = await createGateDirectory('payments-sync-empty')
+
+    try {
+      // No Stripe key at all: the file check comes first, so this path needs no service and no key.
+      const run = await runHearthkitCliGate({
+        argv: ['payments', 'sync'],
+        cwd: emptyDirectoryPath,
+        env: {},
+      })
+
+      const failure = expectCliFailure(run, 'cli-payments-catalog-not-found', 1)
+      expect(isAbsolute(failure.catalogPath)).toBe(true)
+      expect(failure.catalogPath).toBe(resolve(emptyDirectoryPath, defaultPaymentsCatalogPath))
+      expect(failure.message.startsWith(cliPaymentsCatalogNotFoundErrorPrefix)).toBe(true)
+      expect(run.standardError).toContain(failure.message)
+      expect(run.standardOutput.trim()).toBe('')
+    } finally {
+      await removeGateDirectory(emptyDirectoryPath)
+    }
+  })
+
+  it('fails with cli-payments-catalog-unloadable when the --catalog file exists but exports no catalog', async () => {
+    const { cliPaymentsCatalogUnloadableErrorPrefix } = await loadHearthkitCliPaymentsExports()
+    const unusableCatalogFileName = 'gate-unusable-catalog.ts'
+    const unusableCatalogFilePath = await writeGateCliUnusableCatalogFile({
+      directoryPath: gateDirectoryPath,
+      fileName: unusableCatalogFileName,
+    })
+
+    const run = await runHearthkitCliGate({
+      argv: ['payments', 'sync', '--catalog', `./${unusableCatalogFileName}`],
+      cwd: gateDirectoryPath,
+      env: {},
+    })
+
+    const failure = expectCliFailure(run, 'cli-payments-catalog-unloadable', 1)
+    // The file is there, so this is not "not found", and the flag value is resolved against cwd.
+    expect(failure.catalogPath).toBe(unusableCatalogFilePath)
+    expect(failure.loadFailureDetail.length).toBeGreaterThan(0)
+    expect(failure.message.startsWith(cliPaymentsCatalogUnloadableErrorPrefix)).toBe(true)
+    expect(run.standardError).toContain(failure.message)
+  })
+
+  it('wraps the payments failure as cli-payments-sync-failed when STRIPE_SECRET_KEY is unset', async () => {
+    const { cliPaymentsSyncFailedErrorPrefix, stripeSecretKeyEnvVariableName } =
+      await loadHearthkitCliPaymentsExports()
+    const catalogNames = uniqueGateCliCatalogNames('unset-key')
+    const unsetKeyCatalogFileName = 'gate-unset-key-catalog.ts'
+    await writeGateCliCatalogFile({
+      directoryPath: gateDirectoryPath,
+      fileName: unsetKeyCatalogFileName,
+      catalogNames,
+    })
+
+    // The catalog loads, so the run gets as far as createPaymentsClient, which rejects the env
+    // object. A missing key is deliberately not a CLI failure kind; it arrives wrapped.
+    const run = await runHearthkitCliGate({
+      argv: ['payments', 'sync', '--catalog', `./${unsetKeyCatalogFileName}`],
+      cwd: gateDirectoryPath,
+      env: {},
+    })
+
+    const failure = expectCliFailure(run, 'cli-payments-sync-failed', 1)
+    expect(failure.paymentsFailure.kind).toBe('payments-input-invalid')
+    if (failure.paymentsFailure.kind === 'payments-input-invalid') {
+      expect(failure.paymentsFailure.invalidFieldName).toBe('payments-env')
+    }
+    expect(failure.message.startsWith(cliPaymentsSyncFailedErrorPrefix)).toBe(true)
+    // Both prefixes stay greppable: the payments message follows the CLI prefix unchanged.
+    expect(failure.message).toContain(failure.paymentsFailure.message)
+    // The payments message names the field, not the variable, so the CLI's guidance names it.
+    expect(run.standardError).toContain(stripeSecretKeyEnvVariableName)
+    expect(run.standardError).toContain(failure.message)
+  })
+})

package/src/run-hearthkit-cli.ts

@@ -0,0 +1,62 @@
+import type { CliCommandInvocation, CliCommandResult, RunHearthkitCli } from './cli-contract.ts'
+import type { CliRuntimeContext } from './cli-runtime-context.ts'
+import { parseCliInvocation } from './parse-cli-invocation.ts'
+import { reportCliOutcome } from './report-cli-outcome.ts'
+import { runDbLifecycleCommand } from './run-db-lifecycle-command.ts'
+import { runDevCommand } from './run-dev-command.ts'
+import { runDevInfraDownCommand, runDevInfraUpCommand } from './run-dev-infra-command.ts'
+import { runDoctorCommand } from './run-doctor-checks.ts'
+import { runPaymentsSyncCommand } from './run-payments-sync-command.ts'
+
+/**
+ * Runs one hearthkit command end to end: resolve the working directory and environment, parse argv,
+ * hand the invocation to the package that owns the work, then print and score the outcome. Every
+ * contract failure comes back as a result with an exit code; nothing here throws to report one.
+ */
+export const runHearthkitCli: RunHearthkitCli = async (options) => {
+  const context: CliRuntimeContext = {
+    workingDirectoryPath: options.cwd ?? process.cwd(),
+    environmentVariables: options.env ?? process.env,
+  }
+
+  const parse = parseCliInvocation({ argv: options.argv, context })
+  if (parse.kind === 'cli-invocation-rejected') {
+    return {
+      exitCode: reportCliOutcome({ result: parse.failure, invocation: undefined }),
+      result: parse.failure,
+    }
+  }
+
+  const result = await runCliCommandInvocation({ invocation: parse.invocation, context })
+  return {
+    exitCode: reportCliOutcome({ result, invocation: parse.invocation }),
+    result,
+  }
+}
+
+/** Dispatches a parsed invocation to the one handler that owns it; the switch is the whole command registry. */
+async function runCliCommandInvocation(options: {
+  invocation: CliCommandInvocation
+  context: CliRuntimeContext
+}): Promise<CliCommandResult> {
+  const { invocation, context } = options
+
+  if (invocation.commandPath === 'dev') {
+    return runDevCommand(context)
+  }
+  if (invocation.commandPath === 'dev infra up') {
+    return runDevInfraUpCommand(context)
+  }
+  if (invocation.commandPath === 'dev infra down') {
+    return runDevInfraDownCommand(context)
+  }
+  if (invocation.commandPath === 'doctor') {
+    return runDoctorCommand(context)
+  }
+  if (invocation.commandPath === 'payments sync') {
+    return runPaymentsSyncCommand({ catalogPath: invocation.catalogPath, context })
+  }
+  // Everything left is a db command, and it has to be: a command path added to the enum without a
+  // handler here fails to typecheck against DbLifecycleInvocation rather than falling through.
+  return runDbLifecycleCommand({ invocation, context })
+}

package/src/run-payments-sync-command.ts

@@ -0,0 +1,113 @@
+import { createDrizzleClient, postgresConnectionStringSchema } from '@hearthkit/db'
+import type { PaymentsCatalog, PaymentsEnvValues } from '@hearthkit/payments/payments-contract'
+import { z } from 'zod'
+import { stripeSecretKeyEnvVariableName, type CliCommandResult } from './cli-contract.ts'
+import {
+  paymentsCatalogNotFoundFailure,
+  paymentsCatalogUnloadableFailure,
+  paymentsSyncFailedFailure,
+} from './cli-failure-results.ts'
+import type { CliRuntimeContext } from './cli-runtime-context.ts'
+import { loadPaymentsCatalogModule } from './load-payments-catalog-module.ts'
+import { readEnvironmentVariableValue } from './read-environment-variable-value.ts'
+
+/**
+ * hearthkit payments sync: resolve the catalog file, hand it to @hearthkit/payments, map the result.
+ *
+ * The file checks come first so a project with no catalog fails without a Stripe key. Everything
+ * after that belongs to payments: the catalog value is passed on unvalidated, and a missing
+ * STRIPE_SECRET_KEY is not a CLI failure kind — it arrives as the payments env failure, wrapped.
+ *
+ * @hearthkit/payments is imported inside the function rather than at the top of the file, so the one
+ * command that syncs a catalog is the only one that pays for loading the Stripe SDK. Every other
+ * command, and the bin's own startup, stays free of it.
+ */
+
+// Sync verifies no signature, runs no query and writes no customer row, so the CLI supplies the rest
+// of the payments client itself rather than asking the operator for it: a placeholder webhook secret,
+// a Drizzle client aimed at a port nothing listens on, and organizationsEnabled false. A sync that
+// ever grew a query would report a wrapped payments-database-unavailable rather than touch a real
+// database, which is the direction this is meant to fail in.
+/** Webhook secret handed to createPaymentsClient because its env fragment requires one; sync never verifies a signature. */
+const unusedWebhookSecretPlaceholder = 'hearthkit-cli-payments-sync-unused-webhook-secret'
+
+/** Connection string the throwaway Drizzle client points at; a pool opens no connection until a query runs, and sync runs none. */
+const unusedProjectDatabaseUrl = postgresConnectionStringSchema.parse(
+  'postgresql://hearthkit:hearthkit@127.0.0.1:1/hearthkit-cli-payments-sync-unused',
+)
+
+// Both of these pass a value straight through with the type @hearthkit/payments declares and no check
+// of their own. That is the contract: createPaymentsClient is what validates a catalog and an env
+// object, so a bad catalog comes back as payments-catalog-invalid and an unset key as
+// payments-input-invalid with payments-env, rather than as a second opinion formed here.
+/** Passes the catalog module's export through unvalidated, because createPaymentsClient validates it. */
+const unvalidatedPaymentsCatalogSchema = z.custom<PaymentsCatalog>()
+
+/** Passes the env object through unvalidated, because createPaymentsClient rejects a missing key as payments-env. */
+const unvalidatedPaymentsEnvSchema = z.custom<PaymentsEnvValues>()
+
+/** Runs one payments sync invocation and returns the success shape or the CLI failure that wraps what payments said. */
+export async function runPaymentsSyncCommand(options: {
+  catalogPath: string
+  context: CliRuntimeContext
+}): Promise<CliCommandResult> {
+  const { catalogPath, context } = options
+
+  const catalogLoad = await loadPaymentsCatalogModule(catalogPath)
+  if (catalogLoad.kind === 'payments-catalog-file-absent') {
+    return paymentsCatalogNotFoundFailure(catalogPath)
+  }
+  if (catalogLoad.kind === 'payments-catalog-unloadable') {
+    return paymentsCatalogUnloadableFailure(catalogPath, catalogLoad.loadFailureDetail)
+  }
+
+  const { createPaymentsClient, syncPaymentsCatalog } = await import('@hearthkit/payments')
+
+  const stripeSecretKey =
+    readEnvironmentVariableValue(context.environmentVariables, stripeSecretKeyEnvVariableName) ?? ''
+
+  const { drizzleClient, closeDatabaseClient } = createDrizzleClient<Record<string, unknown>>({
+    databaseUrl: unusedProjectDatabaseUrl,
+    schema: {},
+  })
+
+  try {
+    const clientResult = createPaymentsClient({
+      paymentsEnv: unvalidatedPaymentsEnvSchema.parse({
+        STRIPE_SECRET_KEY: stripeSecretKey,
+        STRIPE_WEBHOOK_SECRET: unusedWebhookSecretPlaceholder,
+      }),
+      drizzleClient,
+      paymentsCatalog: unvalidatedPaymentsCatalogSchema.parse(catalogLoad.catalogValue),
+      organizationsEnabled: false,
+    })
+    if (clientResult.kind !== 'payments-client-created') {
+      return paymentsSyncFailedFailure(clientResult)
+    }
+
+    const syncResult = await syncPaymentsCatalog({ paymentsClient: clientResult.paymentsClient })
+    if (syncResult.kind !== 'payments-catalog-synced') {
+      return paymentsSyncFailedFailure(syncResult)
+    }
+
+    return {
+      kind: 'payments-sync-command-succeeded',
+      catalogPath,
+      syncedPrices: syncResult.syncedPrices,
+      createdPriceCount: countPricesSyncedBy(syncResult.syncedPrices, 'created'),
+      replacedPriceCount: countPricesSyncedBy(syncResult.syncedPrices, 'replaced'),
+      unchangedPriceCount: countPricesSyncedBy(syncResult.syncedPrices, 'unchanged'),
+      stripeLivemode: syncResult.stripeLivemode,
+    }
+  } finally {
+    await closeDatabaseClient()
+  }
+}
+
+/** How many synced prices took one action; the three words are payments' own syncAction values. */
+function countPricesSyncedBy(
+  syncedPrices: readonly { syncAction: string }[],
+  syncAction: string,
+): number {
+  return syncedPrices.filter((syncedPrice) => syncedPrice.syncAction === syncAction).length
+}