create-acmekit-app 2.13.1

package/src/utils/clone-repo.ts

@@ -0,0 +1,117 @@
+import fs from "fs"
+import { Ora } from "ora"
+import path from "path"
+import { isAbortError } from "./create-abort-controller.js"
+import execute from "./execute.js"
+import logMessage from "./log-message.js"
+import { execFileSync } from "child_process"
+
+type CloneRepoOptions = {
+  directoryName?: string
+  repoUrl?: string
+  abortController?: AbortController
+  verbose?: boolean
+  isPlugin?: boolean
+}
+
+const DEFAULT_REPO = "https://github.com/acmekit/acmekit-starter-default"
+const DEFAULT_PLUGIN_REPO = "https://github.com/acmekit/acmekit-starter-plugin"
+const BRANCH = "master"
+const PLUGIN_BRANCH = "main"
+
+export default async function cloneRepo({
+  directoryName = "",
+  repoUrl,
+  abortController,
+  verbose = false,
+  isPlugin = false,
+}: CloneRepoOptions) {
+  const defaultRepo = isPlugin ? DEFAULT_PLUGIN_REPO : DEFAULT_REPO
+  const branch = isPlugin ? PLUGIN_BRANCH : BRANCH
+
+  await execute(
+    [
+      `git clone ${
+        repoUrl || defaultRepo
+      } -b ${branch} ${directoryName} --depth 1`,
+      {
+        signal: abortController?.signal,
+      },
+    ],
+    { verbose }
+  )
+}
+
+export async function runCloneRepo({
+  projectName,
+  repoUrl,
+  abortController,
+  spinner,
+  verbose = false,
+  isPlugin = false,
+}: {
+  projectName: string
+  repoUrl: string
+  abortController: AbortController
+  spinner: Ora
+  verbose?: boolean
+  isPlugin?: boolean
+}) {
+  try {
+    await cloneRepo({
+      directoryName: projectName,
+      repoUrl,
+      abortController,
+      verbose,
+      isPlugin,
+    })
+
+    deleteGitDirectory(projectName)
+  } catch (e) {
+    if (isAbortError(e)) {
+      process.exit()
+    }
+
+    spinner.stop()
+    logMessage({
+      message: `An error occurred while setting up your project: ${e}`,
+      type: "error",
+    })
+  }
+}
+
+function deleteGitDirectory(projectDirectory: string) {
+  try {
+    fs.rmSync(path.join(projectDirectory, ".git"), {
+      recursive: true,
+      force: true,
+    })
+  } catch (error) {
+    deleteWithCommand(projectDirectory, ".git")
+  }
+
+  try {
+    fs.rmSync(path.join(projectDirectory, ".github"), {
+      recursive: true,
+      force: true,
+    })
+  } catch (error) {
+    deleteWithCommand(projectDirectory, ".github")
+  }
+}
+
+/**
+ * Useful for deleting directories when fs methods fail (e.g., with Yarn v3)
+ */
+function deleteWithCommand(projectDirectory: string, dirName: string) {
+  const dirPath = path.normalize(path.join(projectDirectory, dirName))
+  if (!fs.existsSync(dirPath)) {
+    return
+  }
+
+  if (process.platform === "win32") {
+    execFileSync("cmd", ["/c", "rmdir", "/s", "/q", dirPath])
+  } else {
+    execFileSync("rm", ["-rf", dirPath])
+  }
+}

package/src/utils/create-abort-controller.ts

@@ -0,0 +1,16 @@
+import ProcessManager from "./process-manager.js"
+
+export default (processManager: ProcessManager) => {
+  const abortController = new AbortController()
+  processManager.onTerminated(() => abortController.abort())
+  return abortController
+}
+
+export const isAbortError = (e: any) =>
+  e !== null && typeof e === "object" && "code" in e && e.code === "ABORT_ERR"
+
+export const getAbortError = () => {
+  return {
+    code: "ABORT_ERR",
+  }
+}

package/src/utils/create-db.ts

@@ -0,0 +1,245 @@
+import { EOL } from "os"
+import type pg from "@acmekit/deps/pg"
+import postgresClient, {
+  DEFAULT_HOST,
+  DEFAULT_PORT,
+} from "./postgres-client.js"
+import inquirer from "inquirer"
+import logMessage from "./log-message.js"
+import formatConnectionString from "./format-connection-string.js"
+import { Ora } from "ora"
+import { getCurrentOs } from "./get-current-os.js"
+import terminalLink from "terminal-link"
+
+type CreateDbOptions = {
+  client: pg.Client
+  db: string
+}
+
+export default async function createDb({ client, db }: CreateDbOptions) {
+  await client.query(`CREATE DATABASE "${db}"`)
+}
+
+async function doesDbExist(
+  client: pg.Client,
+  dbName: string
+): Promise<boolean> {
+  const result = await client.query(
+    `SELECT datname FROM pg_catalog.pg_database WHERE datname='${dbName}';`
+  )
+
+  return !!result.rowCount
+}
+
+export async function runCreateDb({
+  client,
+  dbName,
+  spinner,
+}: {
+  client: pg.Client
+  dbName: string
+  spinner: Ora
+}): Promise<pg.Client> {
+  let newClient = client
+
+  try {
+    // create postgres database
+    await createDb({
+      client,
+      db: dbName,
+    })
+
+    // create a new connection with database selected
+    await client.end()
+    newClient = await postgresClient({
+      user: client.user,
+      password: client.password,
+      database: dbName,
+    })
+  } catch (e) {
+    spinner.stop()
+    logMessage({
+      message: `An error occurred while trying to create your database: ${e}`,
+      type: "error",
+    })
+  }
+
+  return newClient
+}
+
+async function getForDbName({
+  dbName,
+  verbose = false,
+}: {
+  dbName: string
+  verbose?: boolean
+}): Promise<{
+  client: pg.Client
+  dbConnectionString: string
+  dbName: string
+}> {
+  let client!: pg.Client
+  let postgresUsername = "postgres"
+  let postgresPassword = ""
+
+  const defaultConnectionOptions = {
+    host: DEFAULT_HOST,
+    port: DEFAULT_PORT,
+  }
+
+  try {
+    client = await postgresClient({
+      user: postgresUsername,
+      password: postgresPassword,
+      ...defaultConnectionOptions,
+    })
+  } catch (e) {
+    if (verbose) {
+      logMessage({
+        message: `The following error occured when connecting to the database: ${e}`,
+        type: "verbose",
+      })
+    }
+    // ask for the user's postgres credentials
+    const answers = await inquirer.prompt([
+      {
+        type: "input",
+        name: "postgresUsername",
+        message: "Enter your Postgres username",
+        default: "postgres",
+        validate: (input) => {
+          return typeof input === "string" && input.length > 0
+        },
+      },
+      {
+        type: "password",
+        name: "postgresPassword",
+        message: "Enter your Postgres password",
+      },
+    ])
+
+    postgresUsername = answers.postgresUsername
+    postgresPassword = answers.postgresPassword
+
+    const { userDbName } = await inquirer.prompt([
+      {
+        type: "database",
+        name: "userDbName",
+        message: "Enter your Postgres user's database name",
+        default: answers.postgresUsername,
+        validate: (input) => {
+          return typeof input === "string" && input.length > 0
+        },
+      },
+    ])
+
+    try {
+      client = await postgresClient({
+        user: postgresUsername,
+        password: postgresPassword,
+        database: userDbName,
+        ...defaultConnectionOptions,
+      })
+    } catch (e) {
+      logMessage({
+        message: `Couldn't connect to PostgreSQL because of the following error: ${e}.${EOL}${EOL}Make sure you have PostgreSQL installed and the credentials you provided are correct.${EOL}${EOL}If you keep running into this issue despite having PostgreSQL installed, please check out our ${terminalLink(
+          "troubleshooting guides",
+          "https://docs.acmekit.com/resources/troubleshooting/database-errors"
+        )}.`,
+        type: "error",
+      })
+    }
+  }
+
+  // check if database exists
+  if (await doesDbExist(client, dbName)) {
+    const { newDbName } = await inquirer.prompt([
+      {
+        type: "input",
+        name: "newDbName",
+        message: `A database already exists with the name ${dbName}, please enter a name for the database:`,
+        default: dbName,
+        validate: (input) => {
+          return (
+            typeof input === "string" && input.length > 0 && input !== dbName
+          )
+        },
+      },
+    ])
+
+    dbName = newDbName
+  }
+
+  // format connection string
+  const dbConnectionString = formatConnectionString({
+    user: postgresUsername,
+    password: postgresPassword,
+    host: client!.host,
+    db: dbName,
+  })
+
+  return {
+    client,
+    dbConnectionString,
+    dbName,
+  }
+}
+
+async function getForDbUrl({
+  dbUrl,
+  verbose = false,
+}: {
+  dbUrl: string
+  verbose?: boolean
+}): Promise<{
+  client: pg.Client
+  dbConnectionString: string
+}> {
+  let client!: pg.Client
+
+  try {
+    client = await postgresClient({
+      connectionString: dbUrl,
+    })
+  } catch (e) {
+    if (verbose) {
+      logMessage({
+        message: `The following error occured when connecting to the database: ${e}`,
+        type: "verbose",
+      })
+    }
+    logMessage({
+      message: `Couldn't connect to PostgreSQL using the database URL you passed. Make sure it's correct and try again.`,
+      type: "error",
+    })
+  }
+
+  return {
+    client,
+    dbConnectionString: dbUrl,
+  }
+}
+
+export async function getDbClientAndCredentials({
+  dbName = "",
+  dbUrl = "",
+  verbose = false,
+}): Promise<{
+  client: pg.Client
+  dbConnectionString: string
+  verbose?: boolean
+  dbName?: string
+}> {
+  // Check the db-url first, because the dbName is always defined in AcmeKitProjectCreator->create()->initializeProject()->setupDatabase()
+  if (dbUrl) {
+    return await getForDbUrl({
+      dbUrl,
+      verbose,
+    })
+  } else {
+    return await getForDbName({
+      dbName,
+      verbose,
+    })
+  }
+}

package/src/utils/execute.ts

@@ -0,0 +1,86 @@
+import { exec, spawnSync, SpawnSyncOptions } from "child_process"
+import util from "util"
+import { getAbortError } from "./create-abort-controller.js"
+
+const promiseExec = util.promisify(exec)
+
+export type ExecuteResult = {
+  stdout?: string
+  stderr?: string
+}
+
+export type VerboseOptions = {
+  verbose?: boolean
+  // Since spawn doesn't allow us to both retrieve the
+  // output and output it live without using events,
+  // enabling this option, which is only useful if `verbose` is `true`,
+  // defers the output of the process until after the process is executed
+  // instead of outputting the log in realtime, which is the default.
+  // it prioritizes retrieving the output over outputting it in real-time.
+  needOutput?: boolean
+}
+
+type PromiseExecParams = Parameters<typeof promiseExec>
+type SpawnParams = [string, SpawnSyncOptions]
+
+const execute = async (
+  command: SpawnParams | PromiseExecParams,
+  { verbose = false, needOutput = false }: VerboseOptions
+): Promise<ExecuteResult> => {
+  if (verbose) {
+    const [commandStr, options] = command as SpawnParams
+    const childProcess = spawnSync(commandStr, {
+      ...options,
+      shell: true,
+      stdio: needOutput
+        ? "pipe"
+        : [process.stdin, process.stdout, process.stderr],
+      env: {
+        ...process.env,
+        ...(options.env || {}),
+      },
+    })
+
+    if (childProcess.error || childProcess.status !== 0) {
+      throw (
+        childProcess.error ||
+        childProcess.stderr?.toString() ||
+        `${commandStr} failed with status ${childProcess.status}`
+      )
+    }
+
+    if (
+      childProcess.signal &&
+      ["SIGINT", "SIGTERM"].includes(childProcess.signal)
+    ) {
+      throw getAbortError()
+    }
+
+    if (needOutput) {
+      console.log(
+        childProcess.stdout?.toString() || childProcess.stderr?.toString()
+      )
+    }
+
+    return {
+      stdout: childProcess.stdout?.toString() || "",
+      stderr: childProcess.stderr?.toString() || "",
+    }
+  } else {
+    const [commandStr, options] = command as PromiseExecParams
+    const childProcess = await promiseExec(commandStr, {
+      ...options,
+      env: {
+        ...process.env,
+        ...(options?.env || {}),
+      },
+    })
+
+    return {
+      stdout: childProcess.stdout as string,
+      stderr: childProcess.stderr as string,
+    }
+  }
+}
+
+export default execute

package/src/utils/facts.ts

@@ -0,0 +1,148 @@
+import boxen from "boxen"
+import chalk from "chalk"
+import { emojify } from "node-emoji"
+import { Ora } from "ora"
+import ProcessManager from "./process-manager.js"
+import terminalLink from "terminal-link"
+
+export type FactBoxOptions = {
+  interval: NodeJS.Timeout | null
+  spinner: Ora
+  processManager: ProcessManager
+  message?: string
+  title?: string
+  verbose?: boolean
+}
+
+const facts = [
+  "Specify a product's availability in one or more sales channels.",
+  "Payment providers can be configured per region.",
+  "Tax-inclusive pricing allows you to set prices for products and shipping options while delegating tax calculations to AcmeKit.",
+  "AcmeKit provides multi-currency and region support, with full control over prices for each currency and region.",
+  "Organize customers by customer groups and set special prices for them.",
+  "Specify the inventory of products per location and sales channel.",
+  "Publishable-API Keys allow you to send scoped requests to the server's store API routes.",
+  "API Routes expose business logic to clients, such as storefronts and admin customizations.",
+  "Subscribers are asynchronous functions that are executed when an event is emitted.",
+  "Data models represent tables in the database. They are created using AcmeKit's Data Modeling Language (DML).",
+  "AcmeKit's store API routes are prefixed by /store. The admin API routes are prefixed by /admin.",
+  "The JS SDK allows you to send requests to the AcmeKit server from your storefront or admin customizations.",
+  "Modules are reusable packages of functionalities related to a single commerce domain or integration.",
+  "Modules have a main service that provides data-management and integration functionalities.",
+  "Modules allow you to replace an entire functionality with your custom logic.",
+  "Infrastructure Modules are interchangeable modules that implement features and integrations related to the AcmeKit server's infrastructure.",
+  "Commerce Modules are built-in modules that provide core commerce logic specific to domains like Product, Cart and Order.",
+  "Workflows are a series of queries and actions, called steps, that complete a task.",
+  "A workflow's steps can be retried or rolled back in case of an error.",
+  `AcmeKit provides ${terminalLink(
+    "Claude Code plugins",
+    "https://github.com/acmekit/acmekit-claude-plugins"
+  )} to facilitate your development.`,
+  "AcmeKit provides an MCP server at https://docs.acmekit.com/mcp to support your learning and development experience with AI agents",
+  `AcmeKit is optimized to build custom commerce software with AI agents through its MCP server and ${terminalLink(
+    "Claude Code plugins",
+    "https://github.com/acmekit/acmekit-claude-plugins"
+  )}.`,
+]
+
+export const getFact = () => {
+  const randIndex = Math.floor(Math.random() * facts.length)
+
+  return facts[randIndex]
+}
+
+export const showFact = ({
+  spinner,
+  title,
+  verbose,
+}: Pick<FactBoxOptions, "spinner" | "verbose"> & {
+  title: string
+}) => {
+  const fact = getFact()
+  if (verbose) {
+    spinner.stopAndPersist({
+      symbol: chalk.cyan("⠋"),
+      text: title,
+    })
+  } else {
+    spinner.text = `${title}\n${boxen(`${fact}`, {
+      title: chalk.cyan(`${emojify(":bulb:")} AcmeKit Tips`),
+      titleAlignment: "center",
+      textAlignment: "center",
+      padding: 1,
+      margin: 1,
+    })}`
+  }
+}
+
+export const createFactBox = ({
+  spinner,
+  title,
+  processManager,
+  verbose,
+}: Pick<FactBoxOptions, "spinner" | "processManager" | "verbose"> & {
+  title: string
+}): NodeJS.Timeout => {
+  showFact({ spinner, title, verbose })
+  const interval = setInterval(() => {
+    showFact({ spinner, title, verbose })
+  }, 10000)
+
+  processManager.addInterval(interval)
+
+  return interval
+}
+
+export const resetFactBox = ({
+  interval,
+  spinner,
+  successMessage,
+  processManager,
+  newTitle,
+  verbose,
+}: Pick<
+  FactBoxOptions,
+  "interval" | "spinner" | "processManager" | "verbose"
+> & {
+  successMessage: string
+  newTitle?: string
+}): NodeJS.Timeout | null => {
+  if (interval) {
+    clearInterval(interval)
+  }
+
+  spinner.succeed(chalk.green(successMessage)).start()
+  let newInterval = null
+  if (newTitle) {
+    newInterval = createFactBox({
+      spinner,
+      title: newTitle,
+      processManager,
+      verbose,
+    })
+  }
+
+  return newInterval
+}
+
+export function displayFactBox({
+  interval,
+  spinner,
+  processManager,
+  title = "",
+  message = "",
+  verbose = false,
+}: FactBoxOptions): NodeJS.Timeout | null {
+  if (!message) {
+    return createFactBox({ spinner, title, processManager, verbose })
+  }
+
+  return resetFactBox({
+    interval,
+    spinner,
+    successMessage: message,
+    processManager,
+    newTitle: title,
+    verbose,
+  })
+}

package/src/utils/format-connection-string.ts

@@ -0,0 +1,29 @@
+type ConnectionStringOptions = {
+  user?: string
+  password?: string
+  host?: string
+  db: string
+}
+
+export function encodeDbValue(value: string): string {
+  return encodeURIComponent(value)
+}
+
+export default ({ user, password, host, db }: ConnectionStringOptions) => {
+  let connection = `postgres://`
+  if (user) {
+    connection += encodeDbValue(user)
+  }
+
+  if (password) {
+    connection += `:${encodeDbValue(password)}`
+  }
+
+  if (user || password) {
+    connection += "@"
+  }
+
+  connection += `${host}/${db}`
+
+  return connection
+}

package/src/utils/get-config-store.ts

@@ -0,0 +1,17 @@
+import Configstore from "configstore"
+
+let config: Configstore
+
+export const getConfigStore = (): Configstore => {
+  if (!config) {
+    config = new Configstore(
+      `acmekit`,
+      {},
+      {
+        globalConfigPath: true,
+      }
+    )
+  }
+
+  return config
+}

package/src/utils/get-current-os.ts

@@ -0,0 +1,10 @@
+export const getCurrentOs = (): string => {
+  switch (process.platform) {
+    case "darwin":
+      return "macos"
+    case "linux":
+      return "linux"
+    default:
+      return "windows"
+  }
+}

package/src/utils/log-message.ts

@@ -0,0 +1,28 @@
+import chalk from "chalk"
+import { program } from "commander"
+import { logger } from "./logger.js"
+
+type LogOptions = {
+  message: string
+  type?: "error" | "success" | "info" | "warn" | "verbose"
+  stack?: string
+}
+
+export default ({ message, type = "info", stack }: LogOptions) => {
+  switch (type) {
+    case "info":
+      logger.info(chalk.white(message))
+      break
+    case "success":
+      logger.info(chalk.green(message))
+      break
+    case "warn":
+      logger.warn(chalk.yellow(message))
+      break
+    case "verbose":
+      logger.info(`${chalk.bgYellowBright("VERBOSE LOG:")} ${message}`)
+      break
+    case "error":
+      program.error(chalk.bold.red(message.trim() + (stack || "")))
+  }
+}

package/src/utils/logger.ts

@@ -0,0 +1,10 @@
+import winston from "winston"
+
+const consoleTransport = new winston.transports.Console({
+  format: winston.format.printf((log) => log.message as string),
+})
+const options = {
+  transports: [consoleTransport],
+}
+
+export const logger = winston.createLogger(options)