create-catalyst-app 0.3.0-beta.5 → 0.3.0-canary.1

package/codemod/new-route/index.js

@@ -1,6 +1,6 @@
 const fs = require("fs")
 const path = require("path")
-const pc = require("picocolors")
+const pc = require("ansis")
 const prompts = require("prompts")
 const { program } = require("commander")
 

package/codemod/new-route/template.js

@@ -1,6 +1,6 @@
 const fs = require("fs")
 const path = require("path")
-const pc = require("picocolors")
+const pc = require("ansis")
 
 // Function to create component using given input
 function createNewComponent({ componentName, containersDir }) {

package/codemod/new-route/transformers/createReducer.js

@@ -1,4 +1,4 @@
-const pc = require("picocolors")
+const pc = require("ansis")
 
 module.exports = function (fileInfo, api, options) {
     const jscodeshift = api.jscodeshift

package/codemod/new-route/transformers/createRoute.js

@@ -1,4 +1,4 @@
-const pc = require("picocolors")
+const pc = require("ansis")
 
 module.exports = function (fileInfo, api, options) {
     const jscodeshift = api.jscodeshift

package/codemod/new-route/utils.js

@@ -1,6 +1,6 @@
 const fs = require("fs")
 const path = require("path")
-const pc = require("picocolors")
+const pc = require("ansis")
 const { execFileSync } = require("child_process")
 
 const executable = (command) => (process.platform === "win32" ? `${command}.cmd` : command)

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "create-catalyst-app",
     "bin": "scripts/cli.cjs",
-    "version": "0.3.0-beta.5",
+    "version": "0.3.0-canary.1",
     "description": "cli package to scaffold Catalyst application",
     "repository": {
         "type": "git",
@@ -9,20 +9,30 @@
         "directory": "packages/create-catalyst-app"
     },
     "scripts": {
-        "prettify": "prettier . --write"
+        "prettify": "prettier . --write",
+        "test": "npm run test:types && vitest run",
+        "test:watch": "vitest",
+        "test:types": "tsc --noEmit"
     },
     "dependencies": {
+        "ansis": "^4.3.1",
         "commander": "^8.2.0",
         "fs": "^0.0.1-security",
         "https": "^1.0.0",
         "jscodeshift": "^0.16.0",
-        "picocolors": "^0.1.0",
         "prompts": "^2.4.0",
         "tar": "^7.5.22",
         "validate-npm-package-name": "^5.0.0"
     },
     "devDependencies": {
-        "prettier": "^3.2.5"
+        "@types/node": "^22.20.1",
+        "@vitest/coverage-v8": "4.1.9",
+        "prettier": "^3.2.5",
+        "typescript": "^7.0.2",
+        "vitest": "4.1.9"
     },
-    "license": "MIT"
+    "license": "MIT",
+    "overrides": {
+        "vitest": "4.1.9"
+    }
 }

package/scripts/cli.cjs

@@ -3,12 +3,21 @@ const { execFileSync, execSync } = require("child_process")
 const Commander = require("commander")
 const { Option } = require("commander")
 const prompts = require("prompts")
-const { red, green, cyan, bold } = require("picocolors")
+const { red, green, cyan, 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 outputMode = resolveOutputMode(process.argv)
+// Colored (red) prefix only applies in default mode — verbose/debug boxes
+// own their coloring internally (see errors.cjs#box).
+const printError = (err) => {
+    const debugEnv = outputMode === "debug" ? getDebugEnvInfo() : undefined
+    const formatted = formatError(err, outputMode, debugEnv)
+    console.error(outputMode === "default" ? red(formatted) : formatted)
+}
 const packageRoot = path.join(__dirname, "..")
 const executable = (command) => (process.platform === "win32" ? `${command}.cmd` : command)
 
@@ -65,13 +74,21 @@ const program = new Commander.Command()
             const projectName = config.folderName || (await promptProjectName())
             let isNameValid = validate(projectName)
             if (!isNameValid.validForNewPackages) {
-                isNameValid?.warnings?.forEach?.((item) => console.log(red(item)))
-                isNameValid?.errors?.forEach?.((item) => console.log(red(item)))
+                const reasons = [...(isNameValid?.warnings || []), ...(isNameValid?.errors || [])]
+                printError(
+                    createError("CCA-001", {
+                        details: reasons.length ? reasons.join("; ") : undefined,
+                    })
+                )
                 process.exit(1)
             }
             let projectPath = path.join(process.cwd(), projectName)
             if (fs.existsSync(projectPath)) {
-                console.log(red(`${projectName} already exists, try again.`))
+                printError(
+                    createError("CCA-002", {
+                        message: `${projectName} already exists, try again.`,
+                    })
+                )
                 process.exit(1)
             }
             const projectDescription = config.description || (await promptDescription())
@@ -153,7 +170,8 @@ const program = new Commander.Command()
                         runMcpSetup(newMcpDir, path.join(process.cwd(), projectName))
                     }
                 } catch (error) {
-                    console.error(`Error: ${error.message}`)
+                    const catalystError = error instanceof CCAError ? error : wrapForeignError(error)
+                    printError(catalystError)
                     process.exit(1)
                 } finally {
                     deleteDirectory(tempDir)
@@ -184,8 +202,7 @@ const program = new Commander.Command()
 
                     return tarballFilePath
                 } catch (error) {
-                    console.error(`Error packing npm package: ${error.message}`)
-                    throw error
+                    throw createError("CCA-006", { cause: error })
                 }
             }
 
@@ -219,13 +236,14 @@ const program = new Commander.Command()
                         },
                     })
                 } catch (e) {
-                    console.log("An error occurred", e)
+                    throw createError("CCA-007", { cause: e })
                 }
 
                 console.log(cyan(`Run cd ${projectName} && npm start to get started.`))
             }
         } catch (error) {
-            console.error(red("An error occurred:"), error.message)
+            const catalystError = error instanceof CCAError ? error : wrapForeignError(error)
+            printError(catalystError)
             process.exit(1)
         }
     })
@@ -260,7 +278,8 @@ program
 
             runMcpSetup(mcpDir)
         } catch (error) {
-            console.error(red("An error occurred:"), error.message)
+            const catalystError = error instanceof CCAError ? error : createError("CCA-008", { cause: error })
+            printError(catalystError)
             process.exit(1)
         }
     })
@@ -388,16 +407,16 @@ async function promptMcp() {
 function validateOptions(cmd) {
     // Validate language option
     if (cmd.lang && !["js", "ts"].includes(cmd.lang.toLowerCase())) {
-        throw new Error('Invalid language option. Use "js" or "ts".')
+        throw createError("CCA-003")
     }
 
     // Validate state management option
     if (cmd.stateManagement && !["rtk", "redux", "none"].includes(cmd.stateManagement.toLowerCase())) {
-        throw new Error('Invalid state management option. Use "rtk", "redux", or "none".')
+        throw createError("CCA-004")
     }
 
     if (cmd.yes && typeof cmd.yes !== "boolean") {
-        throw new Error('Invalid option for "yes". Use "-y" or "--yes" to accept defaults.')
+        throw createError("CCA-005")
     }
 }
 
@@ -422,7 +441,7 @@ function createGitignore(projectName) {
     const gitignorePath = `${process.cwd()}${path.sep}${projectName}${path.sep}.gitignore`
 
     if (fs.existsSync(gitignorePath)) {
-        console.log(".gitignore already exists. Please rename or remove it before running the script.")
+        printError(createError("CCA-009"))
         return
     }
 

package/scripts/errors.cjs

@@ -0,0 +1,307 @@
+const pc = require("ansis")
+
+const REPO_BLOB_BASE = "https://github.com/tata1mg/catalyst-core/blob/main/errors"
+
+function docUrl(category, code) {
+    return `${REPO_BLOB_BASE}/${category}/${code}.md`
+}
+
+const ERROR_CODES = {
+    CCA_UPSTREAM_ERROR: "CCA-000",
+    CCA_INVALID_NAME: "CCA-001",
+    CCA_DIRECTORY_EXISTS: "CCA-002",
+    CCA_INVALID_LANGUAGE_OPTION: "CCA-003",
+    CCA_INVALID_STATE_MANAGEMENT_OPTION: "CCA-004",
+    CCA_INVALID_YES_OPTION: "CCA-005",
+    CCA_PACK_FAILED: "CCA-006",
+    CCA_EXTRACTION_FAILED: "CCA-007",
+    CCA_MCP_SETUP_FAILED: "CCA-008",
+    CCA_GITIGNORE_EXISTS: "CCA-009",
+}
+
+// One entry per CCA-owned code, including the CCA-000 wrapper used by
+// wrapForeignError. Foreign errors themselves are never reinterpreted —
+// their original message/code always surfaces via `cause`.
+const ERROR_DEFINITIONS = {
+    [ERROR_CODES.CCA_UPSTREAM_ERROR]: {
+        category: "CCA",
+        defaultMessage: "An upstream command failed",
+        defaultDetails:
+            "This wraps an error from npm, tar, or another upstream tool invoked by create-catalyst-app. See the printed upstream message for the actual cause.",
+        suggestedAction: "Read the upstream error message printed above and fix the underlying issue.",
+    },
+    [ERROR_CODES.CCA_INVALID_NAME]: {
+        category: "CCA",
+        defaultMessage: "Invalid project name",
+        defaultDetails: "The project name is not a valid npm package name.",
+        suggestedAction: "Choose a project name that is a valid npm package name and try again.",
+    },
+    [ERROR_CODES.CCA_DIRECTORY_EXISTS]: {
+        category: "CCA",
+        defaultMessage: "Target directory already exists",
+        defaultDetails: "A file or directory with the project name already exists in the current directory.",
+        suggestedAction: "Choose a different project name, or remove/rename the existing directory.",
+    },
+    [ERROR_CODES.CCA_INVALID_LANGUAGE_OPTION]: {
+        category: "CCA",
+        defaultMessage: "Invalid language option",
+        defaultDetails: 'The --lang option must be "js" or "ts".',
+        suggestedAction: 'Pass --lang js or --lang ts.',
+    },
+    [ERROR_CODES.CCA_INVALID_STATE_MANAGEMENT_OPTION]: {
+        category: "CCA",
+        defaultMessage: "Invalid state management option",
+        defaultDetails: 'The --state-management option must be "rtk", "redux", or "none".',
+        suggestedAction: "Pass a supported --state-management value.",
+    },
+    [ERROR_CODES.CCA_INVALID_YES_OPTION]: {
+        category: "CCA",
+        defaultMessage: "Invalid --yes option",
+        defaultDetails: "The -y/--yes flag does not accept a non-boolean value.",
+        suggestedAction: "Use -y or --yes with no value to accept defaults.",
+    },
+    [ERROR_CODES.CCA_PACK_FAILED]: {
+        category: "CCA",
+        defaultMessage: "Failed to pack create-catalyst-app",
+        defaultDetails: "npm pack could not produce the tarball used to scaffold the new project.",
+        suggestedAction: "Check your npm registry access/network connection and try again.",
+    },
+    [ERROR_CODES.CCA_EXTRACTION_FAILED]: {
+        category: "CCA",
+        defaultMessage: "Failed to extract template files",
+        defaultDetails: "The packed tarball could not be extracted into the new project directory.",
+        suggestedAction: "Ensure the target directory is writable and try again.",
+    },
+    [ERROR_CODES.CCA_MCP_SETUP_FAILED]: {
+        category: "CCA",
+        defaultMessage: "MCP server setup failed",
+        defaultDetails: "Downloading, installing, or configuring the MCP server failed.",
+        suggestedAction: "Check your network connection and re-run `catalyst-mcp` inside the project.",
+    },
+    [ERROR_CODES.CCA_GITIGNORE_EXISTS]: {
+        category: "CCA",
+        defaultMessage: ".gitignore already exists",
+        defaultDetails: "The scaffolded project already contains a .gitignore file.",
+        suggestedAction: "Remove or rename the existing .gitignore before running again, or ignore this warning.",
+    },
+}
+
+function getDefinition(code) {
+    return ERROR_DEFINITIONS[code] || ERROR_DEFINITIONS[ERROR_CODES.CCA_UPSTREAM_ERROR]
+}
+
+function getDocUrl(code) {
+    const def = ERROR_DEFINITIONS[code]
+    if (!def) return docUrl(getDefinition(code).category, ERROR_CODES.CCA_UPSTREAM_ERROR)
+    return docUrl(def.category, code)
+}
+
+class CCAError extends Error {
+    constructor(code, { message, details, suggestedAction, category, docUrl, cause } = {}) {
+        super(message)
+        this.name = "CCAError"
+        this.code = code
+        this.category = category
+        this.details = details
+        this.suggestedAction = suggestedAction
+        this.docUrl = docUrl
+        if (cause !== undefined) this.cause = cause
+    }
+}
+
+/**
+ * Create a CCAError for a code we own, using the registry defaults
+ * unless overridden.
+ */
+function createError(code, overrides = {}) {
+    const def = getDefinition(code)
+    return new CCAError(code, {
+        category: def.category,
+        message: overrides.message || def.defaultMessage,
+        details: overrides.details || def.defaultDetails,
+        suggestedAction: overrides.suggestedAction || def.suggestedAction,
+        docUrl: getDocUrl(code),
+        cause: overrides.cause,
+    })
+}
+
+/**
+ * Wrap a foreign error (npm/tar/git/network) that already carries its own
+ * message. We do not replace or reinterpret it — we attach the generic
+ * CCA-000 wrapper code and preserve the original as `cause`, so the
+ * upstream message is always what gets shown to the user.
+ */
+function wrapForeignError(err) {
+    // Unlike catalyst-core's wrapForeignError (BUNDLE/IOS/ANDROID, each with a
+    // fixed upstream tool name), CCA wraps arbitrary tools (npm/tar/git/network)
+    // with no single name to always show — so the "(upstream: ...)" suffix is
+    // omitted entirely when there's no named code, rather than left dangling.
+    // Trimmed and checked for emptiness too — a blank/whitespace-only .code
+    // (still typeof "string") must not produce a dangling "(upstream: )".
+    const upstreamCode = err && typeof err.code === "string" ? err.code.trim() : ""
+    const message = upstreamCode ? `An upstream command failed (upstream: ${upstreamCode})` : "An upstream command failed"
+    return createError(ERROR_CODES.CCA_UPSTREAM_ERROR, {
+        message,
+        cause: err,
+    })
+}
+
+function formatDefault(err) {
+    const lines = [`[${err.code}] ${err.message}`]
+    if (err.cause) {
+        const causeMessage = err.cause.message || String(err.cause)
+        lines.push(`→ ${causeMessage}`)
+    } else if (err.details) {
+        lines.push(err.details)
+    }
+    if (err.suggestedAction) {
+        lines.push(`Suggested action: ${err.suggestedAction}`)
+    }
+    if (err.docUrl) {
+        lines.push(`Docs: ${err.docUrl}`)
+    }
+    return lines.join("\n")
+}
+
+const BOX_WIDTH = 70
+
+function box(bodyLines) {
+    const top = pc.red(`┌${"─".repeat(BOX_WIDTH)}`)
+    const bottom = pc.red(`└${"─".repeat(BOX_WIDTH)}`)
+    const body = bodyLines.map((line) => (line === "" ? pc.red("│") : `${pc.red("│")} ${line}`))
+    return [top, ...body, bottom].join("\n")
+}
+
+function formatCauseChain(cause) {
+    const lines = []
+    let current = cause
+    let depth = 0
+    while (current) {
+        const prefix = depth === 0 ? "Caused by:" : `  ${"  ".repeat(depth - 1)}Caused by:`
+        lines.push(`${prefix} ${current.message || String(current)}`)
+        current = current.cause
+        depth += 1
+    }
+    return lines
+}
+
+/**
+ * Verbose output: boxed per RFC #155 §3.2 — code, category, timestamp,
+ * problem, suggested action, docs link. Mirrors catalyst-core's
+ * errors/index.js#formatVerbose (kept as a separate CJS implementation
+ * since this package can't depend on catalyst-core's ESM module).
+ */
+function formatVerbose(err) {
+    const lines = [
+        pc.bold(`❌ ${err.message}`),
+        `Code: ${err.code}`,
+        `Category: ${err.category || "UNKNOWN"}`,
+        `Time: ${new Date().toISOString()}`,
+        "",
+    ]
+    if (err.cause) {
+        lines.push(`Problem: ${err.cause.message || String(err.cause)}`)
+        lines.push("")
+    } else if (err.details) {
+        lines.push(`Problem: ${err.details}`)
+        lines.push("")
+    }
+    if (err.suggestedAction) {
+        lines.push("Solution:", `  ${err.suggestedAction}`, "")
+    }
+    if (err.docUrl) {
+        lines.push(`Docs: ${err.docUrl}`)
+    }
+    return box(lines)
+}
+
+/**
+ * Debug output: verbose + full cause chain + stack trace + environment
+ * info. Mirrors catalyst-core's errors/index.js#formatDebug.
+ */
+function formatDebug(err, env) {
+    const lines = [
+        pc.bold(`❌ ${err.message}`),
+        `Code: ${err.code}`,
+        `Category: ${err.category || "UNKNOWN"}`,
+        `Time: ${new Date().toISOString()}`,
+        "",
+    ]
+    if (err.cause) {
+        lines.push(...formatCauseChain(err.cause), "")
+    } else if (err.details) {
+        lines.push(`Problem: ${err.details}`, "")
+    }
+    if (err.suggestedAction) {
+        lines.push("Solution:", `  ${err.suggestedAction}`, "")
+    }
+    if (err.docUrl) {
+        lines.push(`Docs: ${err.docUrl}`, "")
+    }
+    if (env) {
+        lines.push("Environment:")
+        for (const [key, value] of Object.entries(env)) {
+            lines.push(`  ${key}: ${value}`)
+        }
+        lines.push("")
+    }
+    lines.push("Stack trace:")
+    const stack = (err.cause && err.cause.stack) || err.stack || "(no stack available)"
+    lines.push(...stack.split("\n").map((l) => `  ${l}`))
+    return box(lines)
+}
+
+/**
+ * Format a CCAError for terminal output. Foreign-wrapped errors always show
+ * the original upstream message/code, never a paraphrase of it.
+ *
+ * `mode` mirrors catalyst-core's formatError(err, mode, env) signature —
+ * defaults to "default" so existing single-arg call sites are unaffected.
+ */
+function formatError(err, mode = "default", env) {
+    if (mode === "debug") return formatDebug(err, env)
+    if (mode === "verbose") return formatVerbose(err)
+    return formatDefault(err)
+}
+
+/**
+ * Resolve output mode from CLI args, mirroring catalyst-core's
+ * scripts/scriptUtils.js#resolveOutputMode (bare --verbose/--debug flags,
+ * not key=value pairs).
+ */
+function resolveOutputMode(argv) {
+    const args = argv || process.argv
+    if (args.includes("--debug")) return "debug"
+    if (args.includes("--verbose")) return "verbose"
+    return "default"
+}
+
+/**
+ * Environment info for debug-mode output: CCA's own installed version, Node
+ * version, and platform. Mirrors catalyst-core's scriptUtils.js#getDebugEnvInfo.
+ */
+function getDebugEnvInfo() {
+    let ccaVersion = "unknown"
+    try {
+        ccaVersion = require("../package.json").version
+    } catch {
+        // package.json not resolvable — leave as "unknown"
+    }
+    return {
+        node: process.version,
+        platform: process.platform,
+        createCatalystApp: ccaVersion,
+    }
+}
+
+module.exports = {
+    ERROR_CODES,
+    ERROR_DEFINITIONS,
+    CCAError,
+    createError,
+    wrapForeignError,
+    formatError,
+    resolveOutputMode,
+    getDebugEnvInfo,
+    getDocUrl,
+}

package/scripts/errors.d.cts

@@ -0,0 +1,55 @@
+// Hand-written type declaration for errors.cjs — that file stays plain CJS
+// until a future source conversion (see issue #420); this exists only so
+// require("./errors.cjs") gets real types in test/errors.test.cts instead of
+// `unknown`. Keep in sync with errors.cjs's actual shape by hand for now.
+
+export interface ErrorDefinition {
+    category: string
+    defaultMessage: string
+    defaultDetails: string
+    suggestedAction: string
+}
+
+export type ErrorCodes = Record<string, string>
+export type ErrorDefinitions = Record<string, ErrorDefinition>
+
+export interface CCAErrorOverrides {
+    message?: string
+    details?: string
+    suggestedAction?: string
+    category?: string
+    docUrl?: string
+    cause?: unknown
+}
+
+export class CCAError extends Error {
+    code: string
+    category?: string
+    details?: string
+    suggestedAction?: string
+    docUrl?: string
+    cause?: unknown
+    constructor(code: string, overrides?: CCAErrorOverrides)
+}
+
+export type OutputMode = "default" | "verbose" | "debug"
+
+// formatError's debug mode just does Object.entries(env) and prints each
+// key/value — getDebugEnvInfo() always returns all three fields, but any
+// caller (including tests) may legitimately pass a partial record.
+export type DebugEnvInfo = Partial<{
+    node: string
+    platform: string
+    createCatalystApp: string
+}> &
+    Record<string, string>
+
+export const ERROR_CODES: ErrorCodes
+export const ERROR_DEFINITIONS: ErrorDefinitions
+
+export function createError(code: string, overrides?: CCAErrorOverrides): CCAError
+export function wrapForeignError(err: unknown): CCAError
+export function formatError(err: CCAError, mode?: OutputMode, env?: DebugEnvInfo): string
+export function resolveOutputMode(argv?: string[]): OutputMode
+export function getDebugEnvInfo(): DebugEnvInfo
+export function getDocUrl(code: string): string | null

package/scripts/generateDocs.cjs

@@ -0,0 +1,78 @@
+const { mkdirSync, writeFileSync, readFileSync, readdirSync, rmSync, existsSync } = require("fs")
+const path = require("path")
+const { ERROR_DEFINITIONS } = require("./errors.cjs")
+
+// packages/create-catalyst-app/scripts -> repo root /errors
+const ERRORS_DIR = path.resolve(__dirname, "../../../errors")
+const INDEX_PATH = path.join(ERRORS_DIR, "index.json")
+
+function renderMarkdown(code, def) {
+    return `# ${code}
+
+**Category:** ${def.category}
+
+## Message
+
+${def.defaultMessage}
+
+## Details
+
+${def.defaultDetails}
+
+## Suggested action
+
+${def.suggestedAction}
+`
+}
+
+function clearGeneratedCategoryDirs() {
+    const dir = path.join(ERRORS_DIR, "CCA")
+    if (!existsSync(dir)) return
+    for (const file of readdirSync(dir)) {
+        if (file.endsWith(".md")) rmSync(path.join(dir, file))
+    }
+}
+
+function readExistingIndex() {
+    if (!existsSync(INDEX_PATH)) return {}
+    try {
+        return JSON.parse(readFileSync(INDEX_PATH, "utf8"))
+    } catch {
+        return {}
+    }
+}
+
+function generateDocs() {
+    clearGeneratedCategoryDirs()
+
+    // Merge into the shared errors/index.json rather than overwriting it —
+    // catalyst-core's own generateDocs.js owns every other category.
+    const index = readExistingIndex()
+
+    for (const [code, def] of Object.entries(ERROR_DEFINITIONS)) {
+        const dir = path.join(ERRORS_DIR, def.category)
+        mkdirSync(dir, { recursive: true })
+        const filePath = path.join(dir, `${code}.md`)
+        writeFileSync(filePath, renderMarkdown(code, def))
+
+        index[code] = {
+            category: def.category,
+            message: def.defaultMessage,
+            details: def.defaultDetails,
+            suggestedAction: def.suggestedAction,
+            docUrl: `https://github.com/tata1mg/catalyst-core/blob/main/errors/${def.category}/${code}.md`,
+        }
+    }
+
+    mkdirSync(ERRORS_DIR, { recursive: true })
+    writeFileSync(INDEX_PATH, JSON.stringify(index, null, 4))
+
+    return { count: Object.keys(ERROR_DEFINITIONS).length, errorsDir: ERRORS_DIR }
+}
+
+if (require.main === module) {
+    const { count, errorsDir } = generateDocs()
+    console.log(`Generated ${count} error doc(s) and merged into index.json in ${errorsDir}`)
+}
+
+module.exports = { generateDocs }

package/templates/none-js/client/index.js

@@ -1,7 +1,8 @@
 import React from "react"
 import "./styles"
 import { hydrateRoot } from "react-dom/client"
-import { RouterProvider, hydrationReady } from "catalyst-core"
+import { hydrationReady } from "catalyst-core"
+import { RouterProvider } from "react-router/dom"
 import clientRouter from "catalyst-core/router/ClientRouter"
 
 window.addEventListener("load", () => {

package/templates/none-js/package.json

@@ -22,9 +22,10 @@
         "@routes": "src/js/routes/"
     },
     "dependencies": {
-        "catalyst-core": "0.3.0-beta.5",
+        "catalyst-core": "0.3.0-canary.1",
         "react": "19.0.0",
-        "react-dom": "19.0.0"
+        "react-dom": "19.0.0",
+        "react-router": "^7.18.2"
     },
     "devDependencies": {
         "eslint": "^8.26.0",

package/templates/none-js/src/js/containers/App/index.js

@@ -1,5 +1,5 @@
 import React from "react"
-import { Outlet } from "catalyst-core"
+import { Outlet } from "react-router"
 
 const App = () => {
     return (

package/templates/none-ts/client/index.js

@@ -1,7 +1,8 @@
 import React from "react"
 import "./styles"
 import { hydrateRoot } from "react-dom/client"
-import { RouterProvider, hydrationReady } from "catalyst-core"
+import { hydrationReady } from "catalyst-core"
+import { RouterProvider } from "react-router/dom"
 import clientRouter from "catalyst-core/router/ClientRouter"
 
 window.addEventListener("load", () => {

package/templates/none-ts/package.json

@@ -23,9 +23,10 @@
         "@routes": "src/js/routes/"
     },
     "dependencies": {
-        "catalyst-core": "0.3.0-beta.5",
+        "catalyst-core": "0.3.0-canary.1",
         "react": "19.0.0",
-        "react-dom": "19.0.0"
+        "react-dom": "19.0.0",
+        "react-router": "^7.18.2"
     },
     "devDependencies": {
         "eslint": "^8.26.0",

package/templates/none-ts/src/js/containers/App/index.js

@@ -1,5 +1,5 @@
 import React from "react"
-import { Outlet } from "catalyst-core"
+import { Outlet } from "react-router"
 
 const App = () => {
     return (

package/templates/redux-js/client/index.js

@@ -2,7 +2,8 @@ import React from "react"
 import "./styles"
 import { hydrateRoot } from "react-dom/client"
 import { Provider } from "react-redux"
-import { RouterProvider, hydrationReady } from "catalyst-core"
+import { hydrationReady } from "catalyst-core"
+import { RouterProvider } from "react-router/dom"
 import clientRouter from "catalyst-core/router/ClientRouter"
 import configureStore from "@store"
 

package/templates/redux-js/package.json

@@ -25,9 +25,10 @@
     "dependencies": {
         "@reduxjs/toolkit": "^2.9.0",
         "react-redux": "^9.2.0",
-        "catalyst-core": "0.3.0-beta.5",
+        "catalyst-core": "0.3.0-canary.1",
         "react": "19.0.0",
         "react-dom": "19.0.0",
+        "react-router": "^7.18.2",
         "redux": "^5.0.1"
     },
     "devDependencies": {

package/templates/redux-js/src/js/containers/App/index.js

@@ -1,5 +1,5 @@
 import React from "react"
-import { Outlet } from "catalyst-core"
+import { Outlet } from "react-router"
 
 const App = () => {
     return (

package/templates/redux-ts/client/index.js

@@ -2,7 +2,8 @@ import React from "react"
 import "./styles"
 import { hydrateRoot } from "react-dom/client"
 import { Provider } from "react-redux"
-import { RouterProvider, hydrationReady } from "catalyst-core"
+import { hydrationReady } from "catalyst-core"
+import { RouterProvider } from "react-router/dom"
 import clientRouter from "catalyst-core/router/ClientRouter"
 import configureStore from "@store"
 

package/templates/redux-ts/package.json

@@ -26,9 +26,10 @@
     "dependencies": {
         "@reduxjs/toolkit": "^2.9.0",
         "react-redux": "^9.2.0",
-        "catalyst-core": "0.3.0-beta.5",
+        "catalyst-core": "0.3.0-canary.1",
         "react": "19.0.0",
         "react-dom": "19.0.0",
+        "react-router": "^7.18.2",
         "redux": "^5.0.1"
     },
     "devDependencies": {

package/templates/redux-ts/src/js/containers/App/index.js

@@ -1,5 +1,5 @@
 import React from "react"
-import { Outlet } from "catalyst-core"
+import { Outlet } from "react-router"
 
 const App = () => {
     return (

package/templates/rtk-js/client/index.js

@@ -2,7 +2,8 @@ import React from "react"
 import "./styles"
 import { hydrateRoot } from "react-dom/client"
 import { Provider } from "react-redux"
-import { RouterProvider, hydrationReady } from "catalyst-core"
+import { hydrationReady } from "catalyst-core"
+import { RouterProvider } from "react-router/dom"
 import clientRouter from "catalyst-core/router/ClientRouter"
 import configureStore from "@store"
 

package/templates/rtk-js/package.json

@@ -25,9 +25,10 @@
     "dependencies": {
         "@reduxjs/toolkit": "^2.9.0",
         "react-redux": "^9.2.0",
-        "catalyst-core": "0.3.0-beta.5",
+        "catalyst-core": "0.3.0-canary.1",
         "react": "19.0.0",
         "react-dom": "19.0.0",
+        "react-router": "^7.18.2",
         "redux": "^5.0.1"
     },
     "devDependencies": {

package/templates/rtk-js/src/js/containers/App/index.js

@@ -1,5 +1,5 @@
 import React from "react"
-import { Outlet } from "catalyst-core"
+import { Outlet } from "react-router"
 
 const App = () => {
     return (

package/templates/rtk-ts/client/index.js

@@ -2,7 +2,8 @@ import React from "react"
 import "./styles"
 import { hydrateRoot } from "react-dom/client"
 import { Provider } from "react-redux"
-import { RouterProvider, hydrationReady } from "catalyst-core"
+import { hydrationReady } from "catalyst-core"
+import { RouterProvider } from "react-router/dom"
 import clientRouter from "catalyst-core/router/ClientRouter"
 import configureStore from "@store"
 

package/templates/rtk-ts/package.json

@@ -26,9 +26,10 @@
     "dependencies": {
         "@reduxjs/toolkit": "^2.9.0",
         "react-redux": "^9.2.0",
-        "catalyst-core": "0.3.0-beta.5",
+        "catalyst-core": "0.3.0-canary.1",
         "react": "19.0.0",
         "react-dom": "19.0.0",
+        "react-router": "^7.18.2",
         "redux": "^5.0.1"
     },
     "devDependencies": {

package/templates/rtk-ts/src/js/containers/App/index.js

@@ -1,5 +1,5 @@
 import React from "react"
-import { Outlet } from "catalyst-core"
+import { Outlet } from "react-router"
 
 const App = () => {
     return (

package/test/errors.test.ts

@@ -0,0 +1,219 @@
+// describe/it/expect come from vitest's `globals: true` config (see
+// vitest.config.mjs) — vitest's own exports can't be require()'d, only
+// import'd, so globals injects them instead.
+//
+// errors.cjs itself is loaded via require() rather than import — it's a
+// CommonJS module and this keeps the runtime behavior identical to how
+// every other require("./errors.cjs") call site in this package loads it.
+// require(...) is untyped by default, and errors.cjs stays plain JS until a
+// future source conversion (see issue #420), so we annotate it against the
+// hand-written declaration in ../scripts/errors.d.cts rather than let every
+// usage below infer as `unknown`.
+const cca: typeof import("../scripts/errors.cjs") = require("../scripts/errors.cjs")
+
+// Framework-level (Tier 1) contract + parity tests for the CCA error mirror
+// (packages/create-catalyst-app/scripts/errors.cjs). This is a standalone
+// CJS module — CCA packs/extracts itself before catalyst-core is ever
+// installed, so it can't import catalyst-core/errors and instead re-implements
+// the same shape/conventions by hand (see decision #6 in the story-6
+// checkpoint). These tests assert it stays structurally in sync with those
+// conventions, not that it shares code with catalyst-core (see issue #340/#411).
+
+const CODE_FORMAT_RE = /^[A-Z][A-Z-]*-\d{3}$/
+
+describe("CCA ERROR_CODES / ERROR_DEFINITIONS shape invariants (mirrors registry.test.js's rules)", () => {
+    const { ERROR_CODES, ERROR_DEFINITIONS } = cca
+    const codeEntries = Object.entries(ERROR_CODES)
+    const codeValues = Object.values(ERROR_CODES)
+
+    it("has at least one code defined", () => {
+        expect(codeEntries.length).toBeGreaterThan(0)
+    })
+
+    it("every ERROR_CODES value has a matching ERROR_DEFINITIONS entry", () => {
+        const missing = codeValues.filter((code) => !(code in ERROR_DEFINITIONS))
+        expect(missing).toEqual([])
+    })
+
+    it("code values are unique", () => {
+        const seen = new Set()
+        const duplicates = []
+        for (const code of codeValues) {
+            if (seen.has(code)) duplicates.push(code)
+            seen.add(code)
+        }
+        expect(duplicates).toEqual([])
+    })
+
+    it("every code matches the CATEGORY-NNN format", () => {
+        const malformed = codeValues.filter((code) => !CODE_FORMAT_RE.test(code))
+        expect(malformed).toEqual([])
+    })
+
+    it("every code's category prefix matches its definition's category field", () => {
+        const mismatches = []
+        for (const [key, code] of codeEntries) {
+            const def = ERROR_DEFINITIONS[code]
+            if (!def) continue
+            const prefix = code.slice(0, code.lastIndexOf("-"))
+            if (prefix !== def.category) mismatches.push(`${key} (${code}): prefix "${prefix}" !== category "${def.category}"`)
+        }
+        expect(mismatches).toEqual([])
+    })
+
+    it("every definition has all required fields, non-empty — same required-field set as the core registry", () => {
+        const REQUIRED_FIELDS = ["category", "defaultMessage", "defaultDetails", "suggestedAction"] as const
+        const problems: string[] = []
+        for (const [code, def] of Object.entries(ERROR_DEFINITIONS)) {
+            for (const field of REQUIRED_FIELDS) {
+                const value = def[field]
+                if (typeof value !== "string" || value.trim().length === 0) {
+                    problems.push(`${code}: missing or empty "${field}"`)
+                }
+            }
+        }
+        expect(problems).toEqual([])
+    })
+
+    it("no definition carries a `recoverable` field (dropped repo-wide, including this mirror)", () => {
+        const withRecoverable = Object.entries(ERROR_DEFINITIONS)
+            .filter(([, def]) => "recoverable" in def)
+            .map(([code]) => code)
+        expect(withRecoverable).toEqual([])
+    })
+
+    it("owns exactly one category (CCA) — doesn't collide with any core-owned category", () => {
+        const CORE_CATEGORIES = new Set(["PREFLIGHT", "PROCESS", "BUNDLE", "IOS", "ANDROID", "RUNTIME-NATIVE", "AI", "RUNTIME-WEB"])
+        const ccaCategories = new Set(Object.values(ERROR_DEFINITIONS).map((d) => d.category))
+        const collisions = [...ccaCategories].filter((c) => CORE_CATEGORIES.has(c))
+        expect(collisions).toEqual([])
+        expect(ccaCategories).toEqual(new Set(["CCA"]))
+    })
+})
+
+describe("createError() / getDefinition() — same override + fallback contract as catalyst-core's version", () => {
+    it("uses registry defaults when no overrides are given", () => {
+        const err = cca.createError(cca.ERROR_CODES.CCA_DIRECTORY_EXISTS)
+        expect(err).toBeInstanceOf(cca.CCAError)
+        expect(err.code).toBe("CCA-002")
+        expect(err.category).toBe("CCA")
+        expect(err.message).toBe("Target directory already exists")
+    })
+
+    it("overrides details while falling back to the default message", () => {
+        const err = cca.createError(cca.ERROR_CODES.CCA_UPSTREAM_ERROR, { details: "npm pack exited 1" })
+        expect(err.details).toBe("npm pack exited 1")
+        expect(err.message).toBe("An upstream command failed")
+    })
+
+    it("falls back to the CCA_UPSTREAM_ERROR definition for an unrecognized code (same shape as core's UNKNOWN fallback, different concrete fallback)", () => {
+        const err = cca.createError("NOT-A-REAL-CODE")
+        expect(err.category).toBe("CCA")
+        expect(err.message).toBe("An upstream command failed")
+    })
+
+    it("attaches cause only when explicitly provided", () => {
+        const withoutCause = cca.createError(cca.ERROR_CODES.CCA_DIRECTORY_EXISTS)
+        expect("cause" in withoutCause).toBe(false)
+        const original = new Error("EEXIST")
+        const withCause = cca.createError(cca.ERROR_CODES.CCA_DIRECTORY_EXISTS, { cause: original })
+        expect(withCause.cause).toBe(original)
+    })
+})
+
+describe("wrapForeignError() — same never-reinterpret contract as catalyst-core's wrapForeignError", () => {
+    it("always uses the CCA-000 wrapper code and preserves the original as cause", () => {
+        const original = new Error("ENOENT: no such file or directory")
+        const wrapped = cca.wrapForeignError(original)
+        expect(wrapped.code).toBe(cca.ERROR_CODES.CCA_UPSTREAM_ERROR)
+        expect(wrapped.cause).toBe(original)
+    })
+
+    it("shows the upstream named code when present", () => {
+        // .code isn't part of the standard Error interface — it's a Node
+        // convention (see NodeJS.ErrnoException).
+        const original: NodeJS.ErrnoException = new Error("failed")
+        original.code = "ENOENT"
+        const wrapped = cca.wrapForeignError(original)
+        expect(wrapped.message).toContain("ENOENT")
+    })
+
+    it("omits the \"(upstream: ...)\" suffix entirely when there is no named code, rather than leaving it dangling", () => {
+        const wrapped = cca.wrapForeignError(new Error("generic failure"))
+        expect(wrapped.message).toBe("An upstream command failed")
+    })
+
+    it("omits the suffix for an empty or whitespace-only .code too — still typeof \"string\", but not a real name", () => {
+        const emptyCode: NodeJS.ErrnoException = new Error("failed")
+        emptyCode.code = ""
+        expect(cca.wrapForeignError(emptyCode).message).toBe("An upstream command failed")
+
+        const blankCode: NodeJS.ErrnoException = new Error("failed")
+        blankCode.code = "   "
+        expect(cca.wrapForeignError(blankCode).message).toBe("An upstream command failed")
+    })
+
+    it("trims surrounding whitespace off a real named code", () => {
+        const padded: NodeJS.ErrnoException = new Error("failed")
+        padded.code = "  ENOENT  "
+        expect(cca.wrapForeignError(padded).message).toBe("An upstream command failed (upstream: ENOENT)")
+    })
+})
+
+describe("getDocUrl() — same repo-blob URL convention as catalyst-core's getDocUrl", () => {
+    it("builds a URL under errors/<category>/<code>.md for a known code", () => {
+        expect(cca.getDocUrl(cca.ERROR_CODES.CCA_INVALID_NAME)).toBe(
+            "https://github.com/tata1mg/catalyst-core/blob/main/errors/CCA/CCA-001.md"
+        )
+    })
+
+    it("falls back to the CCA-000 doc URL for an unrecognized code, rather than a broken link", () => {
+        expect(cca.getDocUrl("NOT-A-REAL-CODE")).toBe(
+            "https://github.com/tata1mg/catalyst-core/blob/main/errors/CCA/CCA-000.md"
+        )
+    })
+})
+
+describe("formatError() — same 3-mode contract (default/verbose/debug) as catalyst-core's formatError", () => {
+    it("defaults to \"default\" mode", () => {
+        const err = cca.createError(cca.ERROR_CODES.CCA_DIRECTORY_EXISTS)
+        expect(cca.formatError(err)).toBe(cca.formatError(err, "default"))
+    })
+
+    it("default mode includes code, message, and suggested action", () => {
+        const err = cca.createError(cca.ERROR_CODES.CCA_DIRECTORY_EXISTS)
+        const output = cca.formatError(err, "default")
+        expect(output).toContain("[CCA-002]")
+        expect(output).toContain("Suggested action:")
+    })
+
+    it("verbose mode is boxed and includes Code/Category/Solution/Docs", () => {
+        const err = cca.createError(cca.ERROR_CODES.CCA_DIRECTORY_EXISTS)
+        const output = cca.formatError(err, "verbose")
+        expect(output).toContain("Code: CCA-002")
+        expect(output).toContain("Category: CCA")
+        expect(output).toContain("Solution:")
+        expect(output).toContain("┌")
+    })
+
+    it("debug mode includes the cause chain and a Stack trace section", () => {
+        const original = new Error("root cause")
+        const err = cca.createError(cca.ERROR_CODES.CCA_UPSTREAM_ERROR, { cause: original })
+        const output = cca.formatError(err, "debug", { node: "v20.4.0" })
+        expect(output).toContain("Caused by: root cause")
+        expect(output).toContain("Environment:")
+        expect(output).toContain("Stack trace:")
+    })
+})
+
+describe("resolveOutputMode() — same bare-flag contract as scriptUtils.js#resolveOutputMode", () => {
+    it("detects --debug and --verbose from an argv array", () => {
+        expect(cca.resolveOutputMode(["node", "cli.js", "--debug"])).toBe("debug")
+        expect(cca.resolveOutputMode(["node", "cli.js", "--verbose"])).toBe("verbose")
+        expect(cca.resolveOutputMode(["node", "cli.js"])).toBe("default")
+    })
+
+    it("--debug takes priority when both flags are present", () => {
+        expect(cca.resolveOutputMode(["--verbose", "--debug"])).toBe("debug")
+    })
+})

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+    "compilerOptions": {
+        /* Type-checks test/ only (via `tsc --noEmit`) — scripts/errors.cjs and
+         * the rest of create-catalyst-app's source stay plain JS/CJS until a
+         * future source conversion (see issue #420). This exists for
+         * editor/CI type-checking; vitest transpiles .ts test files via
+         * esbuild at run time and doesn't need this config to execute them. */
+        "target": "es2022",
+        "lib": ["es2022"],
+        "module": "node16",
+        "moduleResolution": "node16",
+        "allowJs": true,
+        "checkJs": false,
+        "strict": true,
+        "esModuleInterop": true,
+        "forceConsistentCasingInFileNames": true,
+        "skipLibCheck": true,
+        "types": ["node", "vitest/globals"],
+        "noEmit": true
+    },
+    "include": ["test"],
+    "exclude": ["node_modules"]
+}

package/vitest.config.mjs

@@ -0,0 +1,24 @@
+import { defineConfig } from "vitest/config"
+
+// Framework-level (Tier 1) unit tests for create-catalyst-app's own
+// internals — see test/*.test.ts. errors.cjs is a standalone CJS mirror of
+// catalyst-core's error registry shape (it can't depend on catalyst-core —
+// CCA packs/extracts itself before catalyst-core is ever installed), so its
+// parity test lives here rather than in catalyst-core's test suite.
+export default defineConfig({
+    test: {
+        environment: "node",
+        include: ["test/**/*.test.ts"],
+        // errors.cjs itself is CommonJS (see its own file header), loaded
+        // via require() from the .ts test file below — TypeScript allows
+        // require() in a .ts file (it's still just a global Node function),
+        // it just doesn't get CJS *emit* semantics the way .cts would.
+        // .cts was tried first and rejected: this Vite/Rollup version's SSR
+        // transform doesn't strip TS syntax from .cts files at all (fails
+        // to parse even a single `const x: number` type annotation) — a
+        // real tooling gap, not a config mistake. vitest's own describe/it/
+        // expect exports can't be require()'d, only import'd — globals
+        // injects them instead.
+        globals: true,
+    },
+})