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.

11.7 KB
Raw Blame
import fs from 'node:fs'
import path from 'node:path'
import * as p from '@clack/prompts'
import { execa } from 'execa'
import pc from 'picocolors'
import { setupAgents } from './agents.js'
import { DASHBOARD_PORT, SELLER_DASHBOARD_PORT, STOREFRONT_REPO } from './constants.js'
import { scaffoldApp } from './dashboard.js'
import { downloadServer } from './server.js'
import { installRootDeps, scaffoldStorefront } from './storefront.js'
import { agentsMdContent, claudeMdContent } from './templates/agents-md.js'
import { dependabotContent } from './templates/dependabot.js'
import { envContent } from './templates/env.js'
import { dockerignoreContent, gitignoreContent } from './templates/gitignore.js'
import { rootPackageJsonContent } from './templates/package-json.js'
import { readmeContent } from './templates/readme.js'
import type { PackageManager, ScaffoldOptions } from './types.js'
import {
  generateEncryptionKeys,
  generateSecretKeyBase,
  installCommand,
  isDockerRunning,
  runCommand,
  storefrontPm,
} from './utils.js'

export async function scaffold(options: ScaffoldOptions): Promise<void> {
  const projectDir = path.resolve(options.directory)
  const projectName = path.basename(projectDir)
  const { port, storefront, dashboard, sellerDashboard } = options

  // Pre-flight checks
  if (options.start) {
    const dockerRunning = await isDockerRunning()
    if (!dockerRunning) {
      p.cancel('Docker is not running. Please start Docker and try again, or use --no-start.')
      process.exit(1)
    }
  }

  if (fs.existsSync(projectDir)) {
    const entries = fs.readdirSync(projectDir)
    if (entries.length > 0) {
      p.cancel(`Directory ${pc.bold(options.directory)} is not empty.`)
      process.exit(1)
    }
  }

  const s = p.spinner()

  fs.mkdirSync(projectDir, { recursive: true })

  // Phase 1: Download server (always included)
  s.start('Downloading server template...')
  await downloadServer(projectDir)
  s.stop('Server template downloaded.')

  // Phase 2: Generate project files
  s.start('Creating project structure...')

  // Copy compose files from server template and adjust paths for project root
  const serverDir = path.join(projectDir, 'server')
  const compose = fs.readFileSync(path.join(serverDir, 'docker-compose.yml'), 'utf-8')
  const composeDev = fs.readFileSync(path.join(serverDir, 'docker-compose.dev.yml'), 'utf-8')

  fs.writeFileSync(path.join(projectDir, 'docker-compose.yml'), compose)
  // Adjust build context and source bind-mount from current dir to ./server
  // for the wrapper project (in the starter repo the compose file lives in
  // the Rails app root; here the app lives under server/)
  fs.writeFileSync(
    path.join(projectDir, 'docker-compose.dev.yml'),
    composeDev
      .replace('context: .', 'context: ./server')
      .replace('- .:/rails', '- ./server:/rails'),
  )

  // The compose files now live (adjusted) at the wrapper root referencing
  // ./server + the root .env. The originals cloned into server/ are stale
  // leftovers (mount .:/rails, expect a sibling .env) — remove them so the CLI
  // never accidentally targets them when run from server/.
  fs.rmSync(path.join(serverDir, 'docker-compose.yml'), { force: true })
  fs.rmSync(path.join(serverDir, 'docker-compose.dev.yml'), { force: true })

  fs.writeFileSync(
    path.join(projectDir, '.env'),
    envContent(
      generateSecretKeyBase(),
      port,
      options.mailpitSmtpPort,
      options.mailpitUiPort,
      generateEncryptionKeys(),
    ),
    // Holds SECRET_KEY_BASE and the encryption keys — owner-only.
    { mode: 0o600 },
  )
  fs.writeFileSync(
    path.join(projectDir, 'package.json'),
    rootPackageJsonContent(projectName, options.packageManager),
  )
  fs.writeFileSync(path.join(projectDir, '.gitignore'), gitignoreContent())
  fs.writeFileSync(path.join(projectDir, '.dockerignore'), dockerignoreContent())

  s.stop('Project structure created.')

  // Install root dependencies (@spree/cli)
  s.start('Installing dependencies...')
  await installRootDeps(projectDir, options.packageManager)
  s.stop('Dependencies installed.')

  // Phase 3: the apps — Dashboard, Seller Panel, then storefront. Their
  // failures warn and continue: they must never abort the scaffold before
  // Phase 4, since `spree init` is what guarantees a fresh Spree image
  // (skipping it leaves a stale local `latest` to boot) and a seeded,
  // credentialed server. A failed app's partial directory is removed so the
  // recovery command, which expects it absent, actually works.
  const run = runCommand(options.packageManager)
  const tryApp = async (dir: string, recovery: string, step: () => Promise<void>) => {
    try {
      await step()
      return true
    } catch (err) {
      fs.rmSync(path.join(projectDir, 'apps', dir), { recursive: true, force: true })
      p.log.warn(
        `Continuing without apps/${dir}/ — add it later with ${pc.bold(recovery)}.\n${errorMessage(err)}`,
      )
      return false
    }
  }
  const appOpts = { install: true, packageManager: options.packageManager }

  const dashboardReady =
    dashboard &&
    (await tryApp('dashboard', `${run} spree add dashboard`, () =>
      scaffoldApp(projectDir, 'dashboard', appOpts),
    ))
  const sellerDashboardReady =
    sellerDashboard &&
    (await tryApp('seller-dashboard', `${run} spree add seller-dashboard`, () =>
      scaffoldApp(projectDir, 'seller-dashboard', appOpts),
    ))
  const storefrontReady =
    storefront &&
    (await tryApp('storefront', `git clone ${STOREFRONT_REPO} apps/storefront`, () =>
      scaffoldStorefront(projectDir, port, options.packageManager),
    ))

  // Project docs are generated only now, from the phases' actual outcomes —
  // a README written up front from the requested flags would document apps
  // whose setup failed.
  fs.writeFileSync(
    path.join(projectDir, 'README.md'),
    readmeContent(
      projectName,
      storefrontReady,
      port,
      dashboardReady,
      options.packageManager,
      sellerDashboardReady,
    ),
  )
  fs.writeFileSync(
    path.join(projectDir, 'AGENTS.md'),
    agentsMdContent(storefrontReady, dashboardReady, options.packageManager, sellerDashboardReady),
  )
  fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), claudeMdContent())
  const githubDir = path.join(projectDir, '.github')
  fs.mkdirSync(githubDir, { recursive: true })
  fs.writeFileSync(
    path.join(githubDir, 'dependabot.yml'),
    dependabotContent(storefrontReady, dashboardReady, sellerDashboardReady),
  )

  // Runs after AGENTS.md exists, which `spree add ai` points at the docs
  // server. A failure warns and continues, like the apps: agent setup is a
  // convenience, never a reason to stop before Phase 4.
  let agentsReady = options.agentSkills && options.docsMcp
  if (options.agentSkills || options.docsMcp) {
    s.start('Setting up AI coding agents...')
    try {
      await setupAgents(projectDir, {
        skills: options.agentSkills,
        mcp: options.docsMcp,
        packageManager: options.packageManager,
      })
      s.stop('AI coding agents set up.')
    } catch (err) {
      agentsReady = false
      s.stop('AI coding agents were only partly set up.')
      p.log.warn(errorMessage(err))
    }
  }

  // Phase 4: Initialize and start services
  if (options.start) {
    // Sample data is never part of a scaffold: first-run setup configures the
    // store through the dashboard, and the sample-data import needs an admin
    // that setup has not created yet — loading it here failed the whole init.
    // The CLI still offers it on demand via `spree sample-data`.
    const initArgs = ['spree', 'init', '--no-sample-data']

    try {
      await execa(runCommand(options.packageManager), initArgs, {
        cwd: projectDir,
        stdio: 'inherit',
      })
    } catch {
      // init streams its own output, so the underlying failure is already on
      // screen — what the operator needs from us is the recovery command.
      throw new Error(
        `Setup did not finish. Start your app with: cd ${projectName} && ${options.packageManager} run dev — the first run completes setup automatically.`,
      )
    }

    if (storefrontReady) {
      p.log.info(
        `${pc.bold('Storefront')}: ${pc.cyan(`cd ${projectName}/apps/storefront && ${storefrontPm(options.packageManager)} run dev`)}`,
      )
    }
    if (sellerDashboardReady) {
      p.log.info(
        `${pc.bold('Seller Panel')}: ${pc.cyan(`cd ${projectName}/apps/seller-dashboard && ${options.packageManager} run dev`)} ${pc.dim(`→ http://localhost:${SELLER_DASHBOARD_PORT}`)}`,
      )
    }
    // No dashboard line here — with the dashboard chosen, `spree init`'s
    // summary already leads with it (served at /dashboard, plus the
    // customize command).
    if (!agentsReady) p.note(agentSetupHint(options.packageManager).join('\n'), 'AI coding agents')
  } else {
    printSuccessWithoutDocker(
      projectName,
      port,
      storefrontReady,
      dashboardReady,
      sellerDashboardReady,
      agentsReady,
      options.packageManager,
    )
  }
}

function printSuccessWithoutDocker(
  projectName: string,
  port: number,
  hasStorefront: boolean,
  hasDashboard: boolean,
  hasSellerDashboard: boolean,
  agentsReady: boolean,
  pm: PackageManager,
): void {
  const run = runCommand(pm)
  const lines: string[] = [
    '',
    `${pc.bold('Next steps:')}`,
    `  cd ${projectName}`,
    `  ${run} spree dev`,
    `  ${pc.dim('# First run completes setup automatically — pulls the latest image, seeds data, configures API keys.')}`,
  ]

  if (hasStorefront) {
    lines.push(
      '',
      `  ${pc.dim('# In another terminal:')}`,
      `  cd ${projectName}/apps/storefront`,
      `  ${installCommand(pm)}`,
      `  ${pm} run dev`,
    )
  }

  // With apps/dashboard, its dev server is the admin — `spree dev` co-runs it
  // with the API, so the URL is live the moment the stack is up. Without it
  // the API serves the built-in dashboard at /dashboard.
  if (hasDashboard) {
    lines.push(
      '',
      `${pc.bold('Admin Dashboard')}`,
      `  http://localhost:${DASHBOARD_PORT}`,
      `  ${pc.dim('# started automatically by `spree dev`, live-reloading from apps/dashboard/')}`,
      `  ${pc.dim("# you'll create the admin account on first run")}`,
      '',
    )
  } else {
    lines.push(
      '',
      `${pc.bold('Admin Dashboard')}`,
      `  http://localhost:${port}/dashboard`,
      `  ${pc.dim(`# to customize it: ${run} spree add dashboard`)}`,
      '',
    )
  }

  if (hasSellerDashboard) {
    lines.push(
      `${pc.bold('Seller Panel')}`,
      `  ${pc.dim('# In another terminal:')}`,
      `  cd ${projectName}/apps/seller-dashboard`,
      `  ${pm} run dev`,
      `  http://localhost:${SELLER_DASHBOARD_PORT}`,
      `  ${pc.dim('# sellers you invite from the Admin Dashboard sign in here')}`,
      '',
    )
  }

  lines.push(
    `${pc.bold('Customize the Spree API')}`,
    `  ${run} spree eject`,
    `  ${pc.dim('# Then edit server/ — the Rails API app (Gemfile, app/, config/)')}`,
    '',
  )

  if (!agentsReady) lines.push(...agentSetupHint(pm), '')

  lines.push(
    `${pc.bold('Join our Discord')}`,
    `  https://discord.spreecommerce.org`,
    '',
    `${pc.bold('Learn more')}`,
    `  https://spreecommerce.org/docs`,
  )

  p.note(lines.join('\n'), 'Project created!')
}

/** How to finish the agent setup the scaffold skipped or could not complete. */
function agentSetupHint(pm: PackageManager): string[] {
  return [
    `${pc.bold('AI coding agents (optional)')}`,
    `  ${runCommand(pm)} spree add ai`,
    `  ${pc.dim('# Installs the Spree agent skills and connects your agent to the Spree docs')}`,
    `  ${pc.dim('# Safe to re-run; --no-skills or --no-mcp sets up only one of the two')}`,
  ]
}

function errorMessage(err: unknown): string {
  return err instanceof Error ? err.message : String(err)
}