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.

18.5 KB
Raw Blame
import fs from 'node:fs'
import path from 'node:path'
import { fileURLToPath } from 'node:url'
import * as p from '@clack/prompts'
import type { Command } from 'commander'
import { execa } from 'execa'
import pc from 'picocolors'
import { isNotFound } from '../config.js'
import { DASHBOARD_PORT, SELLER_DASHBOARD_PORT } from '../constants.js'
import { detectProject } from '../context.js'
import {
  AGENT_SKILLS_REPO,
  addDocsMcpServer,
  addDocsSectionToAgentInstructions,
  dlxCommand,
  installAgentSkills,
} from '../lib/ai.js'
import {
  EXTENSIONS,
  extensionNames,
  isValidGemName,
  isValidNpmName,
  resolveExtension,
} from '../lib/extensions.js'
import { confirmOrExit } from '../lib/prompt.js'
import type { ProjectContext } from '../types.js'
import { type AddExtensionOptions, addExtension } from './add-extension.js'

/**
 * The two admin SPAs `spree add` can scaffold. They differ only in where they
 * live, which bundled template they come from, and which port they serve on —
 * everything else (env file, install, recovery) is identical, so they share
 * one implementation rather than two that drift.
 */
interface AppSpec {
  /** Directory under `apps/`. */
  dir: string
  /** Template directory name inside the CLI's bundled `templates/`. */
  template: string
  /** Env var overriding the bundled template. */
  templateEnvVar: string
  /** Dev-server port, for the closing summary. */
  port: number
  /** Human name used in prompts and messages. */
  label: string
}

const APPS: Record<string, AppSpec> = {
  dashboard: {
    dir: 'dashboard',
    template: 'dashboard-starter',
    templateEnvVar: 'SPREE_DASHBOARD_TEMPLATE',
    port: DASHBOARD_PORT,
    label: 'Dashboard',
  },
  'seller-dashboard': {
    dir: 'seller-dashboard',
    template: 'seller-dashboard-starter',
    templateEnvVar: 'SPREE_SELLER_DASHBOARD_TEMPLATE',
    port: SELLER_DASHBOARD_PORT,
    label: 'Seller Panel',
  },
}

interface AddDashboardOptions {
  /** Git URL or local directory to copy the starter from. */
  template: string
  /** Run the package-manager install after scaffolding. */
  install: boolean
  /** Skip the final summary note — create-spree-app prints its own. */
  quiet?: boolean
}

interface AddAiOptions {
  /** Install the Spree agent skills. */
  skills: boolean
  /** Connect coding agents to the Spree docs MCP server. */
  mcp: boolean
  /** Skip the final summary note — create-spree-app prints its own. */
  quiet?: boolean
}

// `spree add <thing>` — bolt an optional component or an extension onto an
// existing project. Components (dashboard, seller panel, AI coding agent
// setup) are built in; extensions come from the catalog in extensions.json
// (see docs/plans/6.0-cli-add-extensions.md).
export function registerAddCommand(program: Command) {
  program
    .command('add')
    .description('Add an optional component or an extension to your project')
    .argument(
      '[thing]',
      `Component (dashboard, seller-dashboard, ai) or extension (${extensionNames().join(', ')})`,
    )
    .option('--gem <name>', 'Install a gem that is not in the extension catalog')
    .option('--npm <package>', 'Install a dashboard plugin that is not in the extension catalog')
    .option('-y, --yes', 'Agree to ejecting the project and to installing outside the catalog')
    .option(
      '--template <src>',
      'Starter template: git URL or local path (default: the template bundled with the CLI; env SPREE_DASHBOARD_TEMPLATE / SPREE_SELLER_DASHBOARD_TEMPLATE overrides)',
    )
    .option('--no-install', 'Skip dependency install')
    .option('--no-skills', 'ai: skip installing the Spree agent skills')
    .option('--no-mcp', 'ai: skip connecting coding agents to the Spree docs MCP server')
    .option('--quiet', 'Skip the final summary note (for wrapping tools that print their own)')
    .action(
      async (
        thing: string | undefined,
        flags: {
          template?: string
          install: boolean
          skills: boolean
          mcp: boolean
          quiet?: boolean
          gem?: string
          npm?: string
          yes?: boolean
        },
      ) => {
        if (flags.gem || flags.npm) {
          if (thing) usageError('Pass either a name or --gem/--npm, not both.')
          await addUncataloguedExtension(flags.gem, flags.npm, { yes: Boolean(flags.yes) })
          return
        }
        if (!thing) usageError('Name a component or an extension to add.')

        if (thing === 'ai') {
          if (!flags.quiet) p.intro(pc.bgCyan(pc.black(' Spree AI coding agents ')))
          const ready = await addAi(detectProject(), flags)
          if (!flags.quiet) p.outro(ready ? 'Done!' : 'Done, with warnings.')
          if (!ready) process.exit(1)
          return
        }

        const app = Object.hasOwn(APPS, thing) ? APPS[thing] : undefined
        if (!app) {
          const extension = resolveExtension(thing)
          if (!extension) {
            usageError(
              [
                `Unknown component or extension: ${thing}.`,
                `Components: ${[...Object.keys(APPS), 'ai'].join(', ')}`,
                `Extensions: ${extensionNames().join(', ')}`,
                `For a gem that is not listed, use ${pc.bold('spree add --gem <name>')}.`,
              ].join('\n'),
            )
          }
          p.intro(pc.bgCyan(pc.black(` Spree ${extension.label} `)))
          await addExtension(detectProject(), extension, { yes: Boolean(flags.yes) })
          p.outro('Done!')
          return
        }

        p.intro(pc.bgCyan(pc.black(` Spree ${app.label} `)))
        const ctx = detectProject()
        await addApp(ctx, app, {
          template:
            flags.template ?? process.env[app.templateEnvVar] ?? resolveBundledTemplate(app),
          install: flags.install,
          quiet: flags.quiet,
        })
        p.outro('Done!')
      },
    )
}

function usageError(message: string): never {
  console.error(`\n${pc.red('Error:')} ${message}\n`)
  process.exit(2)
}

/**
 * Install a gem or dashboard plugin named on the command line rather than
 * through the catalog. Names are checked so neither can be read as a flag,
 * and the developer confirms, since nothing vouches for the package.
 */
async function addUncataloguedExtension(
  gem: string | undefined,
  npm: string | undefined,
  opts: AddExtensionOptions,
): Promise<void> {
  if (gem && !isValidGemName(gem)) usageError(`Not a valid gem name: ${gem}`)
  if (npm && !isValidNpmName(npm)) usageError(`Not a valid npm package name: ${npm}`)

  // An official gem named with --gem still installs as the catalog says
  // (pinned to the Spree version where it is released with Spree).
  const catalogued = Object.values(EXTENSIONS).find((entry) => entry.gem === gem)
  const uncatalogued = [catalogued ? undefined : gem, npm].filter(Boolean)
  const label = catalogued?.label ?? uncatalogued.join(' and ')

  p.intro(pc.bgCyan(pc.black(` ${label} `)))
  if (uncatalogued.length > 0) {
    await confirmOrExit(
      `${uncatalogued.join(' and ')} ${uncatalogued.length > 1 ? 'are' : 'is'} not in the Spree extension catalog. Install anyway?`,
      opts.yes,
    )
  }
  await addExtension(
    detectProject(),
    { ...catalogued, label, gem, dashboard: npm ?? catalogued?.dashboard },
    opts,
  )
  p.outro('Done!')
}

/**
 * Set a project up for AI coding agents: connect each agent to the Spree docs
 * MCP server, point the agent instructions at it, and install the Spree agent
 * skills. Safe to re-run — servers already configured are kept as they are.
 *
 * @return false when a step failed and the project is only partly set up
 */
export async function addAi(ctx: ProjectContext, opts: AddAiOptions): Promise<boolean> {
  let ready = true

  if (opts.mcp) {
    const outcomes = addDocsMcpServer(ctx.projectDir)
    for (const [file, outcome] of Object.entries(outcomes)) {
      if (outcome === 'unreadable' || outcome === 'unwritable') {
        ready = false
        p.log.warn(
          `Could not ${outcome === 'unreadable' ? 'read' : 'write'} ${pc.bold(file)}${outcome === 'unreadable' ? ' as JSON' : ''}, so it was left as it is. Add the server by hand: https://spreecommerce.org/docs/developer/agentic/mcp`,
        )
      } else if (!opts.quiet) {
        p.log.info(
          outcome === 'added'
            ? `Added the Spree docs MCP server to ${pc.bold(file)}`
            : `${pc.bold(file)} already lists the Spree docs MCP server`,
        )
      }
    }
    const instructions = addDocsSectionToAgentInstructions(ctx.projectDir)
    for (const file of instructions.updated) {
      if (!opts.quiet) p.log.info(`Pointed ${pc.bold(file)} at the Spree docs MCP server`)
    }
    for (const file of instructions.failed) {
      ready = false
      p.log.warn(`Could not update ${pc.bold(file)}, so agents may not know about the docs server.`)
    }
  }

  if (opts.skills) {
    const packageManager = detectPackageManager(ctx.projectDir, ctx.projectDir)
    const s = p.spinner()
    s.start('Installing Spree agent skills...')
    try {
      await installAgentSkills(ctx.projectDir, packageManager)
      s.stop('Spree agent skills installed.')
    } catch (err) {
      ready = false
      s.stop(pc.yellow('Spree agent skills were not installed.'))
      p.log.warn(
        `Install them later with ${pc.bold(`${dlxCommand(packageManager).join(' ')} skills add ${AGENT_SKILLS_REPO}`)}.\n${err instanceof Error ? err.message : String(err)}`,
      )
    }
  }

  if (!opts.quiet && opts.mcp) {
    p.note(
      [
        'Claude Code asks you to approve the docs server the first time you open',
        'the project; Cursor and VS Code list it in their MCP settings.',
        'Commit the new files so your team gets the same setup.',
      ].join('\n'),
      'AI coding agents set up',
    )
  }

  return ready
}

/**
 * Clone the dashboard starter into `apps/dashboard/` and point it at the
 * project's API. Writes no credentials — the dashboard authenticates admins
 * interactively (email/password → JWT + refresh cookie), and `VITE_`-prefixed
 * env values are compiled into the client bundle, so a key here would ship
 * to every browser.
 *
 * Idempotent: an existing `apps/<dir>/` is left untouched (recovery mode
 * rewrites a missing `.env.local` only).
 */
export async function addApp(
  ctx: ProjectContext,
  app: AppSpec,
  opts: AddDashboardOptions,
): Promise<void> {
  const appDir = path.join(ctx.projectDir, 'apps', app.dir)
  const envPath = path.join(appDir, '.env.local')

  if (fs.existsSync(appDir)) {
    // Recovery: write a missing .env.local (interrupted earlier run) or
    // repair a broken one (old scaffold output) — one gatekeeper for both.
    const env = ensureAppDevEnv(ctx.projectDir, app.dir, ctx.port)
    if (env === 'untouched') {
      p.log.warn(`${pc.bold(`apps/${app.dir}/`)} already exists. Nothing to do.`)
      return
    }
    p.log.info(
      `${env === 'written' ? 'Wrote missing' : 'Repaired'} ${pc.bold(`apps/${app.dir}/.env.local`)}. Nothing else to do.`,
    )
    return
  }

  const s = p.spinner()
  s.start(`Fetching ${app.label.toLowerCase()} starter...`)
  try {
    await fetchTemplate(opts.template, appDir)
    restoreGitignore(appDir)
  } catch (err) {
    s.stop('Fetch failed.')
    p.log.error(err instanceof Error ? err.message : String(err))
    process.exit(1)
  }
  s.stop(`Created ${pc.cyan(`apps/${app.dir}/`)}`)

  writeDashboardEnv(envPath, ctx.port)

  const pm = detectPackageManager(ctx.projectDir, appDir)

  if (opts.install) {
    s.start(`Installing dependencies with ${pm}...`)
    try {
      await execa(pm, ['install'], { cwd: appDir })
      s.stop('Dependencies installed.')
      await generateRouteTree(appDir)
    } catch (err) {
      s.stop(pc.yellow(`${pm} install failed — run it manually in apps/${app.dir}/.`))
      p.log.warn(err instanceof Error ? err.message : String(err))
    }
  }

  if (opts.quiet) return
  p.note(
    [
      `Start it with:`,
      `  ${pc.cyan(`${pm === 'npm' ? 'npx' : pm} spree dev`)}`,
      `  ${pc.dim('# runs the API and the dashboard together')}`,
      ...(opts.install
        ? []
        : [`  ${pc.dim(`# install dependencies first: cd apps/${app.dir} && ${pm} install`)}`]),
      '',
      `Then open ${pc.bold(`http://localhost:${app.port}`)} and sign in.`,
    ].join('\n'),
    `${app.label} added!`,
  )
}

/**
 * A starter template bundled inside this package. Generated at build time
 * from the monorepo's `packages/<name>` (workspace deps rewritten to the
 * published versions — see `scripts/sync-starter.mjs`) and shipped in
 * `dist/templates/`. Bundling them with the CLI keeps each template and the
 * `@spree/*` versions it pins in lockstep with every release — there is no
 * separate template repo to drift.
 */
function resolveBundledTemplate(app: AppSpec): string {
  const here = path.dirname(fileURLToPath(import.meta.url))
  // dev: src/commands/add.ts → ../../templates/<name>
  // built: dist/index.js → dist/templates/<name>
  const candidates = [
    path.resolve(here, '../../templates', app.template),
    path.resolve(here, 'templates', app.template),
  ]
  for (const candidate of candidates) {
    if (fs.existsSync(path.join(candidate, 'package.json'))) return candidate
  }
  console.error(
    `\n${pc.red('Error:')} Bundled ${app.label.toLowerCase()} template not found. In the monorepo, ` +
      `run ${pc.cyan('pnpm build')} in packages/cli first (it generates the templates), ` +
      'or pass --template <path|git-url>.\n',
  )
  process.exit(1)
}

/**
 * Writes the app's `src/routeTree.gen.ts` for the packages just installed.
 *
 * The template's copy was generated in the monorepo, so the first dev start
 * would rewrite it — and Vite reloads the open page when it notices, which is
 * the setup screen a new project opens straight into. Loading the app's own
 * Vite config runs the same generator, with the same extensions, without
 * starting a server, so that first start finds nothing to change.
 */
export async function generateRouteTree(appDir: string): Promise<void> {
  // Best effort: the dev server generates the file on start regardless.
  await execa(
    'node',
    [
      '--input-type=module',
      '-e',
      "const { resolveConfig } = await import('vite'); await resolveConfig({}, 'serve')",
    ],
    { cwd: appDir, reject: false },
  )
}

/**
 * The bundled template ships its `.gitignore` as `gitignore.template`
 * (npm never packs `.gitignore` files) — restore the real name on scaffold.
 */
function restoreGitignore(dir: string): void {
  const template = path.join(dir, 'gitignore.template')
  if (fs.existsSync(template)) fs.renameSync(template, path.join(dir, '.gitignore'))
}

/** Git-clone a URL template, or copy a local directory (used in tests/CI). */
async function fetchTemplate(template: string, dst: string): Promise<void> {
  if (fs.existsSync(template) && fs.statSync(template).isDirectory()) {
    fs.cpSync(template, dst, {
      recursive: true,
      filter: (src) => {
        const base = path.basename(src)
        return base !== 'node_modules' && base !== 'dist' && base !== '.git'
      },
    })
    return
  }

  await execa('git', ['clone', '--depth', '1', '--', template, dst])
  fs.rmSync(path.join(dst, '.git'), { recursive: true, force: true })
}

// Old scaffolds wrote the SDK's absolute-URL switch pointed at localhost —
// requests then bypassed the dev proxy and died on CORS + the SameSite=Lax
// cookie. A localhost value can only be that scaffold output, never a real
// cross-origin production URL, so it's safe to migrate in place.
const BROKEN_SCAFFOLD_ENV = /^VITE_SPREE_API_URL=(https?:\/\/localhost\S*)$/m

/**
 * Writes or repairs `apps/dashboard/.env.local` so dashboard dev works out
 * of the box. Idempotent and cheap — called from `spree add dashboard`,
 * first-run setup, and every `spree dev` boot, covering fresh clones (the
 * file is gitignored) and old scaffolds (see {@link BROKEN_SCAFFOLD_ENV};
 * only that line is rewritten — everything else in the file is user-managed
 * and preserved).
 */
export function ensureAppDevEnv(
  projectDir: string,
  appDirName: string,
  port: number,
): 'written' | 'repaired' | 'untouched' {
  const appDir = path.join(projectDir, 'apps', appDirName)
  if (!fs.existsSync(path.join(appDir, 'package.json'))) return 'untouched'

  const envPath = path.join(appDir, '.env.local')
  let existing: string
  try {
    existing = fs.readFileSync(envPath, 'utf-8')
  } catch (error) {
    if (!isNotFound(error)) throw error // unreadable ≠ missing — never clobber
    writeDashboardEnv(envPath, port)
    return 'written'
  }

  if (!BROKEN_SCAFFOLD_ENV.test(existing)) return 'untouched'
  fs.writeFileSync(
    envPath,
    existing.replace(BROKEN_SCAFFOLD_ENV, `VITE_API_PROXY_TARGET=http://localhost:${port}`),
  )
  return 'repaired'
}

/** Every SPA under `apps/` that `spree dev` and first-run setup keep in sync. */
export const APP_DIRS = Object.values(APPS).map((app) => app.dir)

/**
 * Refresh the dev env file for every scaffolded SPA. Apps that aren't present
 * report 'untouched', so this is safe to call unconditionally.
 */
export function ensureDashboardDevEnv(
  projectDir: string,
  port: number,
): 'written' | 'repaired' | 'untouched' {
  let result: 'written' | 'repaired' | 'untouched' = 'untouched'
  for (const dir of APP_DIRS) {
    const outcome = ensureAppDevEnv(projectDir, dir, port)
    if (outcome !== 'untouched') result = outcome
  }
  return result
}

function writeDashboardEnv(envPath: string, port: number): void {
  fs.writeFileSync(
    envPath,
    [
      '# Dev-server proxy target — where Vite forwards /api and /rails (your',
      '# Rails backend). The SPA stays same-origin with the API: the SDK uses',
      '# relative URLs and the proxy bridges the port gap.',
      '#',
      '# Do NOT set VITE_SPREE_API_URL for local dev — it switches the SDK to',
      '# absolute cross-origin URLs, which breaks on CORS and the SameSite=Lax',
      '# auth cookie. Set it only when building for a deploy where the',
      '# dashboard is hosted on a different origin than the API.',
      '#',
      '# No credentials belong in this file — every VITE_-prefixed value is',
      '# compiled into the client bundle.',
      `VITE_API_PROXY_TARGET=http://localhost:${port}`,
      '',
    ].join('\n'),
  )
}

/** Prefer the project's own package manager (by lockfile); default to pnpm. */
export function detectPackageManager(projectDir: string, appDir: string): string {
  for (const dir of [appDir, projectDir]) {
    if (fs.existsSync(path.join(dir, 'pnpm-lock.yaml'))) return 'pnpm'
    if (fs.existsSync(path.join(dir, 'yarn.lock'))) return 'yarn'
    if (fs.existsSync(path.join(dir, 'package-lock.json'))) return 'npm'
  }
  return 'pnpm'
}