create-catalyst-app 1.0.2-canary.1 → 1.0.2

package/package.json

@@ -1,7 +1,10 @@
 {
     "name": "create-catalyst-app",
     "bin": "scripts/cli.cjs",
-    "version": "1.0.2-canary.1",
+    "version": "1.0.2",
+    "engines": {
+        "node": ">=20.12.0"
+    },
     "description": "cli package to scaffold Catalyst application",
     "repository": {
         "type": "git",
@@ -15,9 +18,10 @@
         "test:types": "tsc --noEmit"
     },
     "dependencies": {
+        "@clack/prompts": "^1.7.0",
         "ansis": "^4.3.1",
         "commander": "^8.2.0",
-        "jscodeshift": "^0.16.0",
+        "jscodeshift": "^17.4.0",
         "prompts": "^2.4.0",
         "tar": "^7.5.22",
         "validate-npm-package-name": "^5.0.0"

package/scripts/cli.cjs

@@ -2,14 +2,25 @@
 const { execFileSync, execSync } = require("child_process")
 const Commander = require("commander")
 const { Option } = require("commander")
-const prompts = require("prompts")
-const { red, green, cyan, bold } = require("ansis")
+// @clack/prompts is ESM-only. require() of ESM is only on by default from
+// Node 20.19 / 22.12 (engines allows >=20.12), so it is imported lazily in the
+// scaffold action -- the only path that uses it.
+/** @type {typeof import("@clack/prompts")} */
+let clack
+const { red, green, cyan, gray, bold } = require("ansis")
 const tar = require("tar")
 const path = require("path")
 const fs = require("fs")
 var validate = require("validate-npm-package-name")
 const packageJson = require("../package.json")
-const { CCAError, createError, wrapForeignError, formatError, resolveOutputMode, getDebugEnvInfo } = require("./errors.cjs")
+const {
+    CCAError,
+    createError,
+    wrapForeignError,
+    formatError,
+    resolveOutputMode,
+    getDebugEnvInfo,
+} = require("./errors.cjs")
 const outputMode = resolveOutputMode(process.argv)
 // Colored (red) prefix only applies in default mode — verbose/debug boxes
 // own their coloring internally (see errors.cjs#box).
@@ -18,6 +29,15 @@ const printError = (err) => {
     const formatted = formatError(err, outputMode, debugEnv)
     console.error(outputMode === "default" ? red(formatted) : formatted)
 }
+// Inside a clack session: close it with a one-line reason tagged with the
+// error's code and its docs link, on stderr like every other error.
+// --verbose/--debug follow it with the registry's full report, which carries
+// the link itself.
+const cancelWithError = (err, message = err.message) => {
+    const docs = outputMode === "default" && err.docUrl ? `\n   ${gray(`Docs: ${err.docUrl}`)}` : ""
+    clack.cancel(`${message} ${gray(`[${err.code}]`)}${docs}`, { output: process.stderr })
+    if (outputMode !== "default") printError(err)
+}
 const packageRoot = path.join(__dirname, "..")
 const executable = (command) => (process.platform === "win32" ? `${command}.cmd` : command)
 
@@ -54,15 +74,20 @@ const program = new Commander.Command()
                 return
             }
 
-            console.log(cyan(`Using create-catalyst-app version ${bold(packageJson.version)}`))
+            clack = await import("@clack/prompts")
+
+            // Same identity as every other Catalyst command: accent-coloured
+            // name, dim version.
+            clack.intro(`${cyan(bold("create-catalyst-app"))} ${gray(packageJson.version)}`)
 
             // Use options provided through commander or prompt the user
             validateOptions(cmd)
 
             if (cmd.yes) {
-                console.log("Using default configuration.")
+                clack.log.info("Using default configuration")
                 config = {
-                    folderName: "my-app",
+                    // A name given on the command line still wins over the default.
+                    folderName: folderName || "my-app",
                     language: "js",
                     tailWindSupport: false,
                     description: "Default catalyst app",
@@ -72,30 +97,37 @@ const program = new Commander.Command()
             }
 
             const projectName = config.folderName || (await promptProjectName())
-            let isNameValid = validate(projectName)
+
+            // Still needed for --yes and for a name passed as an argument:
+            // those paths never reach the prompt's own validation.
+            const isNameValid = validate(projectName)
             if (!isNameValid.validForNewPackages) {
-                const reasons = [...(isNameValid?.warnings || []), ...(isNameValid?.errors || [])]
-                printError(
-                    createError("CCA-001", {
-                        details: reasons.length ? reasons.join("; ") : undefined,
-                    })
+                const reasons = [...(isNameValid.errors || []), ...(isNameValid.warnings || [])]
+                cancelWithError(
+                    createError("CCA-001", { details: reasons.length ? reasons.join("; ") : undefined }),
+                    `"${projectName}" is not a valid package name: ${reasons.join(", ")}`
                 )
                 process.exit(1)
             }
+            // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - projectName is checked by validate-npm-package-name (no separators or ..) before use.
             let projectPath = path.join(process.cwd(), projectName)
             if (fs.existsSync(projectPath)) {
-                printError(
+                cancelWithError(
                     createError("CCA-002", {
-                        message: `${projectName} already exists, try again.`,
+                        message: `${projectName} already exists — choose another name or remove it.`,
                     })
                 )
                 process.exit(1)
             }
             const projectDescription = config.description || (await promptDescription())
             const language = config.language || (await promptTypescript())
-            const tailWindSupport = config.tailWindSupport !== null || (await promptTailwind())
+            // These are booleans, so `!== null` collapsed a configured `false`
+            // into `true` -- `--yes` installed Tailwind against its own default.
+            // Only fall through to the prompt when nothing was configured.
+            const tailWindSupport =
+                config.tailWindSupport != null ? config.tailWindSupport : await promptTailwind()
             const stateManagement = config.stateManagement || (await promptStateManagement())
-            const mcpSupport = config.mcpSupport !== null || (await promptMcp())
+            const mcpSupport = config.mcpSupport != null ? config.mcpSupport : await promptMcp()
 
             // Define mapping of options to repository suffixes
             const repositorySuffixes = {
@@ -126,52 +158,80 @@ const program = new Commander.Command()
                     extractSubdirectory(packageFilePath)
                     createGitignore(projectName)
 
-                    execSync(
-                        `cd ${projectName} && npm i && npm pkg set name=${projectName} ${projectDescription ? `description="${projectDescription}"` : ""} && git init --quiet`,
-                        { stdio: "inherit" }
-                    )
+                    // npm's install output is hundreds of lines nobody reads
+                    // when it works. Fold it behind a spinner, and print it in
+                    // full only if the step actually fails.
+                    runStep(`Installing dependencies`, () => {
+                        runQuiet(
+                            `cd ${projectName} && npm i && npm pkg set name=${projectName} ${projectDescription ? `description="${projectDescription}"` : ""} && git init --quiet`
+                        )
+                    })
 
                     if (tailWindSupport) {
-                        execSync(`cd ${projectName} && npm i tailwindcss@4.1.4 @tailwindcss/postcss@4.1.4`, {
-                            stdio: "inherit",
+                        runStep("Adding Tailwind CSS", () => {
+                            runQuiet(
+                                `cd ${projectName} && npm i tailwindcss@4.1.4 @tailwindcss/postcss@4.1.4`
+                            )
                         })
                     }
 
-                    execSync(
-                        `cd ${projectName} && git add . && git commit -m "initial commit from Create Catalyst App"`,
-                        {
-                            stdio: "inherit",
-                        }
-                    )
-
-                    console.log(`\n${green(bold("Success!"))} created ${projectName} at ${projectPath}`)
-                    console.log("Inside this directory, you can run the following commands.")
-
-                    console.log(cyan(bold(" \n npm run start")))
-                    console.log("  Starts the development server ")
-
-                    console.log(cyan(bold("\n npm run build")))
-                    console.log("  Bundles the app for production ")
-
-                    console.log(cyan(bold("\n npm run serve")))
-                    console.log("  Serves the production build ")
-
-                    console.log("\nWe suggest you to begin, by running")
-                    console.log(` ${cyan("cd")} ${projectName} && ${cyan("npm start")} \n\n`)
+                    runStep("Creating initial commit", () => {
+                        runQuiet(
+                            `cd ${projectName} && git add . && git commit -m "initial commit from Create Catalyst App"`
+                        )
+                    })
 
+                    let mcpEntry = null
                     if (mcpSupport) {
                         const newMcpDir = path.join(
                             process.cwd(),
-                            projectName,
+                            projectName, // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - projectName is checked by validate-npm-package-name (no separators or ..) before use.
                             "node_modules",
                             "catalyst-core",
                             "mcp_v2"
                         )
-                        runMcpSetup(newMcpDir, path.join(process.cwd(), projectName))
+                        // Same treatment as the install: the setup script's
+                        // own transcript (npm warnings, audit notices, DB
+                        // paths) only matters when it fails.
+                        const transcript = runStep(
+                            "Setting up the MCP server",
+                            () =>
+                                runMcpSetup(newMcpDir, path.join(process.cwd(), projectName), { quiet: true }) // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - projectName is checked by validate-npm-package-name (no separators or ..) before use.
+                        )
+                        for (const warning of mcpWarnings(transcript)) clack.log.warn(warning)
+                        // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - newMcpDir is built from the validated projectName.
+                        mcpEntry = path.join(newMcpDir, "mcp.js")
+                    }
+
+                    clack.note(
+                        [
+                            `${cyan("npm start".padEnd(16))}${gray("Start the development server")}`,
+                            `${cyan("npm run build".padEnd(16))}${gray("Bundle the app for production")}`,
+                            `${cyan("npm run serve".padEnd(16))}${gray("Serve the production build")}`,
+                        ].join("\n"),
+                        `Created ${bold(projectName)}`
+                    )
+
+                    if (mcpEntry) {
+                        // The one thing from the MCP setup a person has to act
+                        // on: the entry to paste into their MCP client.
+                        clack.note(
+                            [
+                                gray("Add to your MCP client (Claude, Cursor, Windsurf):"),
+                                `"catalyst-mcp": {`,
+                                `  "command": "node",`,
+                                `  "args": ["${mcpEntry}"]`,
+                                `}`,
+                            ].join("\n"),
+                            "MCP server"
+                        )
                     }
+
+                    clack.outro(`Next: ${cyan(`cd ${projectName}`)} && ${cyan("npm start")}`)
                 } catch (error) {
+                    // The step that failed already printed its own output.
                     const catalystError = error instanceof CCAError ? error : wrapForeignError(error)
-                    printError(catalystError)
+                    cancelWithError(catalystError, `Could not create ${projectName}: ${error.message}`)
                     process.exit(1)
                 } finally {
                     deleteDirectory(tempDir)
@@ -238,8 +298,6 @@ const program = new Commander.Command()
                 } catch (e) {
                     throw createError("CCA-007", { cause: e })
                 }
-
-                console.log(cyan(`Run cd ${projectName} && npm start to get started.`))
             }
         } catch (error) {
             const catalystError = error instanceof CCAError ? error : wrapForeignError(error)
@@ -286,7 +344,13 @@ program
 
 program.parse(process.argv)
 
-function runMcpSetup(mcpDir, cwd = process.cwd()) {
+/**
+ * @param {string} mcpDir
+ * @param {string} [cwd]
+ * @param {{quiet?: boolean}} [options] - quiet captures the output and returns
+ *   it (printed only on failure); otherwise it streams, for `catalyst-mcp`.
+ */
+function runMcpSetup(mcpDir, cwd = process.cwd(), { quiet = false } = {}) {
     const pkgPath = `${mcpDir}${path.sep}package.json`
     const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"))
     pkg.dependencies["better-sqlite3"] = "^12.8.0"
@@ -295,113 +359,181 @@ function runMcpSetup(mcpDir, cwd = process.cwd()) {
     const mcpNodeModules = `${mcpDir}${path.sep}node_modules`
     let needsInstall = !fs.existsSync(mcpNodeModules)
 
+    const say = (message) => (quiet ? null : console.log(cyan(message)))
+
     if (!needsInstall) {
         try {
             execSync(`node -e "require('better-sqlite3')"`, { cwd: mcpDir, stdio: "pipe" })
         } catch {
-            console.log(cyan("Detected incompatible better-sqlite3 build. Reinstalling..."))
+            say("Detected incompatible better-sqlite3 build. Reinstalling...")
             fs.rmSync(mcpNodeModules, { recursive: true, force: true })
             needsInstall = true
         }
     }
 
-    if (needsInstall) {
-        console.log(cyan("Installing mcp_v2 dependencies..."))
-        execSync("npm install", { cwd: mcpDir, stdio: "inherit" })
+    if (!quiet) {
+        if (needsInstall) {
+            say("Installing mcp_v2 dependencies...")
+            execSync("npm install", { cwd: mcpDir, stdio: "inherit" })
+        }
+        execFileSync(process.execPath, [`${mcpDir}${path.sep}setup.js`], { cwd, stdio: "inherit" })
+        return ""
     }
 
-    execFileSync(process.execPath, [`${mcpDir}${path.sep}setup.js`], { cwd, stdio: "inherit" })
+    let transcript = ""
+    if (needsInstall) transcript += runQuiet(`npm install --no-audit --no-fund`, { cwd: mcpDir })
+    transcript += runQuiet(`"${process.execPath}" "${mcpDir}${path.sep}setup.js"`, { cwd })
+    return transcript
 }
 
-async function promptStateManagement() {
-    const response = await prompts({
-        type: "select",
-        name: "stateManagement",
-        message: "Choose state management:",
-        choices: [
-            { title: "Redux", value: "redux" },
-            { title: "Redux Toolkit (RTK)", value: "rtk" },
-            { title: "None", value: "none" },
-        ],
-    })
+/**
+ * Warnings worth surfacing from an otherwise-hidden MCP setup transcript, e.g.
+ * a knowledge-base sync that could not reach GitHub. The setup marks them ⚠.
+ */
+function mcpWarnings(transcript) {
+    const lines = String(transcript || "").split("\n")
+    const warnings = []
+    for (const [index, line] of lines.entries()) {
+        const match = /^\s*⚠\s*(.+)$/.exec(line)
+        if (!match) continue
+        const next = lines[index + 1]?.trim()
+        warnings.push(next && !/^[⚠✓]/.test(next) ? `${match[1]}. ${next}` : match[1])
+    }
+    return warnings
+}
 
-    return response.stateManagement
+/**
+ * Run a command with its output captured rather than inherited.
+ *
+ * On failure the captured output is printed, so a broken install still shows
+ * npm's actual error instead of just a non-zero exit code.
+ */
+function runQuiet(command, { cwd } = {}) {
+    try {
+        // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process - Internal scaffolding commands built from a validated project name.
+        return execSync(command, { stdio: ["ignore", "pipe", "pipe"], encoding: "utf8", cwd })
+    } catch (error) {
+        const details = [error.stdout, error.stderr].filter(Boolean).join("\n").trim()
+        if (details) {
+            process.stderr.write(`\n${details}\n`)
+        }
+        throw error
+    }
 }
-async function promptProjectName() {
-    const res = await prompts({
-        type: "text",
-        name: "path",
-        message: "What is your project named?",
-        initial: "my-app",
-    })
 
-    if (typeof res.path === "string") {
-        let projectName = res.path.trim()
-        return projectName
+/**
+ * Announce a step, run it, and report the outcome.
+ *
+ * Deliberately not clack's spinner: the work below is synchronous (execSync),
+ * so a spinner's timer never fires and the user stares at one frozen frame for
+ * the whole of `npm i` -- which reads as a hang. A static line that says what
+ * is happening is honest; a stopped animation is not.
+ */
+function runStep(message, fn) {
+    // Announced before, not after: the work below is synchronous (execSync),
+    // so nothing else can report progress while `npm i` runs for minutes. One
+    // line per step -- the failure branch is what changes the outcome, and it
+    // says so explicitly.
+    clack.log.step(message)
+    try {
+        return fn()
+    } catch (error) {
+        clack.log.error(`${message} failed`)
+        throw error
     }
+}
 
-    if (!res.path || projectName === "") {
-        console.log(
-            "\nPlease specify the project directory:\n" +
-                `  ${cyan(program.name())} ${green("<project-directory>")}\n` +
-                "For example:\n" +
-                `  ${cyan(program.name())} ${green("my-next-app")}\n\n` +
-                `Run ${cyan(`${program.name()} --help`)} to see all options.`
-        )
-        process.exit(1)
+/**
+ * Exit cleanly when the user hits Ctrl-C.
+ *
+ * The previous prompt library returned undefined on cancel and the scaffolder
+ * carried on with it, producing a half-configured project from an answer the
+ * user never gave.
+ */
+function exitIfCancelled(value) {
+    if (clack.isCancel(value)) {
+        clack.cancel("Cancelled — nothing was created.")
+        process.exit(130)
     }
+    return value
 }
 
-async function promptDescription() {
-    const res = await prompts({
-        type: "text",
-        name: "path",
-        message: "What is your project description?",
-    })
+async function promptStateManagement() {
+    return exitIfCancelled(
+        await clack.select({
+            message: "Choose state management",
+            options: [
+                { value: "none", label: "None" },
+                { value: "redux", label: "Redux" },
+                { value: "rtk", label: "Redux Toolkit (RTK)" },
+            ],
+            initialValue: "none",
+        })
+    )
+}
+
+async function promptProjectName() {
+    return exitIfCancelled(
+        await clack.text({
+            message: "What is your project named?",
+            placeholder: "my-app",
+            defaultValue: "my-app",
+            validate(value) {
+                const name = (value || "my-app").trim()
+                const result = validate(name)
+                if (!result.validForNewPackages) {
+                    return (result.errors || result.warnings || ["Invalid package name"])[0]
+                }
+                // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - projectName is checked by validate-npm-package-name (no separators or ..) before use.
+                if (fs.existsSync(path.join(process.cwd(), name))) {
+                    return `${name} already exists in this directory`
+                }
+                return undefined
+            },
+        })
+    ).trim()
+}
 
-    if (typeof res.path === "string") {
-        return res.path.trim()
-    } else return null
+async function promptDescription() {
+    const value = exitIfCancelled(
+        await clack.text({
+            message: "What is your project description?",
+            placeholder: "optional",
+            defaultValue: "",
+        })
+    )
+    return value ? value.trim() : null
 }
 
 async function promptTypescript() {
-    const response = await prompts({
-        type: "select",
-        name: "typescript",
-        message: "Would you like to use TypeScript?",
-        choices: [
-            { title: "Yes", value: "ts" },
-            { title: "No", value: "js" },
-        ],
-    })
-
-    return response.typescript
+    return exitIfCancelled(
+        await clack.select({
+            message: "Would you like to use TypeScript?",
+            options: [
+                { value: "js", label: "JavaScript" },
+                { value: "ts", label: "TypeScript" },
+            ],
+            initialValue: "js",
+        })
+    )
 }
 
 async function promptTailwind() {
-    const response = await prompts({
-        type: "select",
-        name: "tailwind",
-        message: "Would you like to use Tailwind CSS?",
-        choices: [
-            { title: "Yes", value: true },
-            { title: "No", value: false },
-        ],
-    })
-    return response.tailwind
+    return exitIfCancelled(
+        await clack.confirm({
+            message: "Would you like to use Tailwind CSS?",
+            initialValue: false,
+        })
+    )
 }
 
 async function promptMcp() {
-    const response = await prompts({
-        type: "select",
-        name: "mcp",
-        message: "Would you like to setup an MCP server?",
-        choices: [
-            { title: "Yes", value: true },
-            { title: "No", value: false },
-        ],
-    })
-    return response.mcp
+    return exitIfCancelled(
+        await clack.confirm({
+            message: "Would you like to set up an MCP server?",
+            initialValue: true,
+        })
+    )
 }
 
 function validateOptions(cmd) {

package/scripts/errors.cjs

@@ -193,7 +193,7 @@ function formatCauseChain(cause) {
  */
 function formatVerbose(err) {
     const lines = [
-        pc.bold(`❌ ${err.message}`),
+        pc.bold(err.message),
         `Code: ${err.code}`,
         `Category: ${err.category || "UNKNOWN"}`,
         `Time: ${new Date().toISOString()}`,
@@ -221,7 +221,7 @@ function formatVerbose(err) {
  */
 function formatDebug(err, env) {
     const lines = [
-        pc.bold(`❌ ${err.message}`),
+        pc.bold(err.message),
         `Code: ${err.code}`,
         `Category: ${err.category || "UNKNOWN"}`,
         `Time: ${new Date().toISOString()}`,

package/templates/none-js/package.json

@@ -1,6 +1,7 @@
 {
     "name": "create-catalyst-app-starter",
     "version": "1.0.0",
+    "type": "module",
     "scripts": {
         "start": "catalyst start",
         "build": "catalyst build",
@@ -22,7 +23,7 @@
         "@routes": "src/js/routes/"
     },
     "dependencies": {
-        "catalyst-core": "1.0.2-canary.1",
+        "catalyst-core": "1.0.2",
         "react": "19.0.0",
         "react-dom": "19.0.0",
         "react-router": "^7.18.2"

package/templates/none-ts/package.json

@@ -1,6 +1,7 @@
 {
     "name": "create-catalyst-app-starter",
     "version": "1.0.0",
+    "type": "module",
     "scripts": {
         "start": "catalyst start",
         "build": "npm run typecheck && catalyst build",
@@ -23,7 +24,7 @@
         "@routes": "src/js/routes/"
     },
     "dependencies": {
-        "catalyst-core": "1.0.2-canary.1",
+        "catalyst-core": "1.0.2",
         "react": "19.0.0",
         "react-dom": "19.0.0",
         "react-router": "^7.18.2"

package/templates/redux-js/package.json

@@ -1,6 +1,7 @@
 {
     "name": "create-catalyst-app-starter",
     "version": "1.0.0",
+    "type": "module",
     "scripts": {
         "start": "catalyst start",
         "build": "catalyst build",
@@ -25,7 +26,7 @@
     "dependencies": {
         "@reduxjs/toolkit": "^2.9.0",
         "react-redux": "^9.2.0",
-        "catalyst-core": "1.0.2-canary.1",
+        "catalyst-core": "1.0.2",
         "react": "19.0.0",
         "react-dom": "19.0.0",
         "react-router": "^7.18.2",

package/templates/redux-ts/package.json

@@ -1,6 +1,7 @@
 {
     "name": "create-catalyst-app-starter",
     "version": "1.0.0",
+    "type": "module",
     "scripts": {
         "start": "catalyst start",
         "build": "npm run typecheck && catalyst build",
@@ -26,7 +27,7 @@
     "dependencies": {
         "@reduxjs/toolkit": "^2.9.0",
         "react-redux": "^9.2.0",
-        "catalyst-core": "1.0.2-canary.1",
+        "catalyst-core": "1.0.2",
         "react": "19.0.0",
         "react-dom": "19.0.0",
         "react-router": "^7.18.2",

package/templates/rtk-js/package.json

@@ -1,6 +1,7 @@
 {
     "name": "create-catalyst-app-starter",
     "version": "1.0.0",
+    "type": "module",
     "scripts": {
         "start": "catalyst start",
         "build": "catalyst build",
@@ -25,7 +26,7 @@
     "dependencies": {
         "@reduxjs/toolkit": "^2.9.0",
         "react-redux": "^9.2.0",
-        "catalyst-core": "1.0.2-canary.1",
+        "catalyst-core": "1.0.2",
         "react": "19.0.0",
         "react-dom": "19.0.0",
         "react-router": "^7.18.2",

package/templates/rtk-ts/package.json

@@ -1,6 +1,7 @@
 {
     "name": "create-catalyst-app-starter",
     "version": "1.0.0",
+    "type": "module",
     "scripts": {
         "start": "catalyst start",
         "build": "npm run typecheck && catalyst build",
@@ -26,7 +27,7 @@
     "dependencies": {
         "@reduxjs/toolkit": "^2.9.0",
         "react-redux": "^9.2.0",
-        "catalyst-core": "1.0.2-canary.1",
+        "catalyst-core": "1.0.2",
         "react": "19.0.0",
         "react-dom": "19.0.0",
         "react-router": "^7.18.2",

package/test/cli-require-esm.test.ts

@@ -0,0 +1,38 @@
+// engines allows Node >=20.12, but require() of an ES module is only on by
+// default from 20.19 / 22.12. On older runtimes a top-level require() of an
+// ESM-only dependency (e.g. @clack/prompts) kills `npx create-catalyst-app`
+// with ERR_REQUIRE_ESM before it prints anything. Simulate those runtimes by
+// turning require(esm) off and check the CLI still starts.
+const { spawnSync }: typeof import("child_process") = require("child_process")
+const path: typeof import("path") = require("path")
+
+const cli = path.join(__dirname, "..", "scripts", "cli.cjs")
+const canDisableRequireEsm = process.allowedNodeEnvironmentFlags.has("--no-experimental-require-module")
+
+describe.runIf(canDisableRequireEsm)("cli.cjs without require(esm)", () => {
+    it("prints --help", () => {
+        const result = spawnSync(process.execPath, ["--no-experimental-require-module", cli, "--help"], {
+            encoding: "utf8",
+        })
+        expect(result.stderr).not.toContain("ERR_REQUIRE_ESM")
+        expect(result.status).toBe(0)
+        expect(result.stdout).toContain("Usage:")
+    })
+
+    it("loads the prompt library when scaffolding", () => {
+        // An invalid name fails validation right after the prompt library is
+        // imported, so nothing is created.
+        const result = spawnSync(
+            process.execPath,
+            ["--no-experimental-require-module", cli, "Bad Name", "-y"],
+            {
+                encoding: "utf8",
+                env: { ...process.env, NO_COLOR: "1" },
+            }
+        )
+        const output = result.stdout + result.stderr
+        expect(output).not.toContain("ERR_REQUIRE_ESM")
+        expect(output).toContain("CCA-001")
+        expect(result.status).toBe(1)
+    })
+})