Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

9.1 KB
Raw Blame
import fs from 'node:fs'
import * as p from '@clack/prompts'
import type { Command } from 'commander'
import pc from 'picocolors'
import { projectCredentialsPath, projectSetupMarkerPath, readAdminEmail } from '../config.js'
import { DASHBOARD_PORT } from '../constants.js'
import {
  detectProject,
  hasMonorepoSpreePath,
  isEjectedProject,
  readSampleDataFromEnv,
} from '../context.js'
import {
  dashboardDevRunnable,
  hasDashboardApp,
  startDashboardDevServer,
  warnDashboardNotRunnable,
} from '../dashboard-server.js'
import { appServices, dockerCompose, hasProjectContainers, primeBundleVolume } from '../docker.js'
import { ensureDashboardDevEnv } from './add.js'
import { openBrowser, runFirstRunSetup, waitForHealthy } from './init.js'

export function registerDevCommand(program: Command): void {
  program
    .command('dev')
    .description(
      'Run the app in the foreground — the API, plus the Admin Dashboard dev server when apps/dashboard exists; Ctrl+C stops them',
    )
    .option('--no-open', 'skip opening the dashboard in the browser once it is ready')
    .action(async (flags: { open: boolean }) => {
      const ctx = detectProject()

      if (hasMonorepoSpreePath(ctx.projectDir)) {
        p.cancel(
          [
            'This project uses SPREE_PATH for monorepo development.',
            `Use ${pc.bold('pnpm server:dev')} from the monorepo root instead of ${pc.bold('spree dev')}.`,
            'It loads the edge compose overlay and sets SPREE_PATH so the Spree gems resolve to the monorepo source.',
          ].join('\n'),
        )
        process.exit(1)
      }

      // Every boot, not just first run: cheap and idempotent, and it's how
      // projects scaffolded by older CLIs (broken .env.local) get repaired —
      // they already completed setup, so the first-run path below never
      // reaches them.
      ensureDashboardDevEnv(ctx.projectDir, ctx.port)

      // A project that was never set up gets the full first-run flow instead
      // of a bare `up`: pull a fresh image (a mutable tag cached weeks ago by
      // another project would otherwise boot an old Spree), seed the database,
      // mint API keys. This keeps create-spree-app's contract — the app just
      // works — on every path to a first boot (--no-start, an interrupted
      // scaffold, a fresh clone) without requiring anyone to run `spree init`.
      // Completed setup writes a marker (separate from credentials.json,
      // which `spree auth logout` deletes — losing auth must not look like a
      // fresh project). Credentials still count as "set up" for projects
      // initialized by older CLIs that minted them without a marker. When
      // both are missing: a project whose .env declares SPREE_SAMPLE_DATA was
      // scaffolded by a create-spree-app that persists setup state, so that
      // alone means setup never finished — even if an interrupted init
      // already created containers. For older projects the only safe signal
      // is "compose never created a container": an initialized
      // pre-credentials-era project must not be re-set-up (that would load
      // sample data into a real store). Ejected projects build the image
      // locally and manage their own lifecycle.
      if (
        !isEjectedProject(ctx.projectDir) &&
        !fs.existsSync(projectSetupMarkerPath(ctx.projectDir)) &&
        !fs.existsSync(projectCredentialsPath(ctx.projectDir))
      ) {
        let neverSetUp = readSampleDataFromEnv(ctx.projectDir) !== undefined
        if (!neverSetUp) {
          try {
            neverSetUp = !(await hasProjectContainers(ctx.projectDir))
          } catch {
            // Daemon trouble surfaces with compose's own error on the up below.
          }
        }
        if (neverSetUp) {
          p.log.info('First run detected — completing setup automatically.')
          await runFirstRunSetup({ sampleData: true, open: flags.open })
          return
        }
      }

      // The summary and the spawn key off the same runnable check so the
      // card never advertises a dev server that can't start (deps missing).
      const withDashboard = hasDashboardApp(ctx.projectDir) && dashboardDevRunnable(ctx.projectDir)
      if (hasDashboardApp(ctx.projectDir) && !withDashboard) {
        warnDashboardNotRunnable(ctx.projectDir)
      }
      p.note(
        [
          '',
          ...(withDashboard
            ? [
                pc.bold('Admin Dashboard'),
                `  ${pc.cyan(`http://localhost:${DASHBOARD_PORT}`)}`,
                ...adminIdentityLines(ctx.projectDir),
                `  ${pc.dim('Live-reloading from apps/dashboard/')}`,
              ]
            : [
                pc.bold('Admin Dashboard'),
                `  ${pc.dim(`Not installed — add it with ${pc.bold('spree add dashboard')}`)}`,
                ...adminIdentityLines(ctx.projectDir),
              ]),
          '',
          pc.bold('Store API'),
          `  ${pc.cyan(`http://localhost:${ctx.port}/api/v3/store`)}`,
          '',
        ].join('\n'),
        'Spree Commerce',
      )

      p.log.info(
        `Starting services — ${withDashboard ? 'API + dashboard logs' : 'API logs'} stream below. ` +
          `${pc.bold('Ctrl+C')} stops them ` +
          `(databases keep running; ${pc.bold('spree stop')} shuts everything down).\n`,
      )

      // Foreground `up`, like `vite dev`: Ctrl+C delivers SIGINT to compose,
      // which gracefully stops web + worker. Dependency services (postgres,
      // mailpit) start via depends_on but stay up afterwards.
      // Ignore SIGINT in the CLI itself so compose owns the shutdown and we
      // live to print the outro.
      const ignoreSigint = () => {}
      process.on('SIGINT', ignoreSigint)
      let result: { exitCode?: number }
      let dashboard: ReturnType<typeof startDashboardDevServer> = null
      const stopWaiting = new AbortController()
      try {
        // Prime the shared bundle_cache volume with web alone first so the
        // foreground `up web worker` below doesn't race the cold-volume
        // copy-up. web is left running and re-attached (its logs still stream);
        // only worker is newly started by the foreground up. Run INSIDE the
        // SIGINT-ignore guard so a Ctrl+C during the brief priming window can't
        // leave the volume half-populated (a partial copy-up would make the
        // next run's emptiness gate lie). On a warm volume this is a ~1s no-op.
        await primeBundleVolume(ctx.projectDir)

        // Co-run the dashboard's Vite dev server with the Docker stack — one
        // command, the whole dev environment. Its output joins the stream
        // below with a `dashboard |` prefix; the terminal's Ctrl+C reaches it
        // alongside compose (same foreground process group), and stop() in
        // the finally covers non-signal exits.
        dashboard = withDashboard ? startDashboardDevServer(ctx.projectDir) : null

        if (flags.open) {
          void openDashboardWhenReady(ctx.port, dashboard, stopWaiting.signal)
        }

        result = await dockerCompose(
          ['up', ...(await appServices(ctx.projectDir))],
          ctx.projectDir,
          {
            stdio: 'inherit',
            reject: false,
          },
        )
      } finally {
        stopWaiting.abort()
        dashboard?.stop()
        process.off('SIGINT', ignoreSigint)
      }

      // Ctrl+C lands in compose as SIGINT → graceful stop, exit code 130.
      // Anything else non-zero is a real failure (daemon down, bad config,
      // port conflict) — surface it instead of pretending shutdown was clean.
      const exitCode = result.exitCode ?? 0
      if (exitCode !== 0 && exitCode !== 130) {
        p.cancel(`docker compose exited with code ${exitCode} — see the output above.`)
        process.exit(exitCode)
      }

      p.outro(
        `${withDashboard ? 'API + dashboard' : 'API'} stopped. Databases keep running — ${pc.bold('spree stop')} shuts everything down.`,
      )
    })
}

/**
 * Opens the dashboard once the API answers its health check — the dashboard
 * is unusable before then — and, with a dashboard app, once Vite reports its
 * URL. Runs alongside the foreground stack; a stack that stops first, an
 * API that never becomes healthy, or a dashboard that never reports ready
 * leaves the browser alone.
 */
async function openDashboardWhenReady(
  port: number,
  dashboard: ReturnType<typeof startDashboardDevServer>,
  signal: AbortSignal,
): Promise<void> {
  try {
    await waitForHealthy(port, signal)
  } catch {
    return
  }
  const url = dashboard ? await dashboard.url : `http://localhost:${port}/dashboard`
  if (!url || signal.aborted) return

  await openBrowser(url)
}

/**
 * Admin sign-in lines for the summary card. An admin only exists if `init`
 * seeded one; otherwise the account is created through first-run setup, so
 * naming an email here would be a guess.
 */
function adminIdentityLines(projectDir: string): string[] {
  const email = readAdminEmail(projectDir)
  if (!email) {
    return [`  ${pc.dim('Create your admin account with the setup link from `spree init`')}`]
  }

  return [`  Email:    ${email}`, `  Password: ${pc.dim('chosen during spree init')}`]
}