@expressots/cli 4.0.0-preview.2 → 4.0.0-preview.3

package/bin/new/form.js

@@ -10,6 +10,7 @@ const degit_1 = __importDefault(require("degit"));
 const inquirer_1 = __importDefault(require("inquirer"));
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const cli_1 = require("../cli");
 const center_text_1 = require("../utils/center-text");
 const change_package_info_1 = require("../utils/change-package-info");
 const cli_ui_1 = require("../utils/cli-ui");
@@ -176,6 +177,7 @@ function copyDirectorySync(src, dest) {
 var Template;
 (function (Template) {
     Template["application"] = "Application :: Full-featured ExpressoTS application. (Recommended)";
+    Template["applicationWithEvents"] = "Application with Events :: Application template pre-wired with the type-safe Event Bus example.";
     Template["micro"] = "Micro :: A minimalistic template for building micro APIs and serverless functions.";
 })(Template || (Template = {}));
 /**
@@ -194,6 +196,7 @@ var MiddlewarePreset;
  */
 const TEMPLATE_FOLDERS = {
     Application: "application",
+    "Application with Events": "application-with-events",
     Micro: "micro",
 };
 /**
@@ -202,10 +205,87 @@ const TEMPLATE_FOLDERS = {
 const PRESET_CODE = {
     API: `this.Middleware.applyPreset("api");`,
     Web: `this.Middleware.applyPreset("web");`,
-    GraphQL: `this.Middleware.applyPreset("graphql");`,
+    GraphQL: [
+        `this.Middleware.applyPreset("graphql");`,
+        ``,
+        `        const apolloServer = new ApolloServer({ typeDefs, resolvers });`,
+        `        await apolloServer.start();`,
+        `        this.Middleware.add({`,
+        `            path: "/graphql",`,
+        `            middlewares: [expressMiddleware(apolloServer)],`,
+        `        });`,
+    ].join("\n"),
     Microservice: `this.Middleware.applyPreset("microservice");`,
     Minimal: `this.Middleware.parse();`,
 };
+/**
+ * Extra imports that specific presets need appended to app.ts.
+ */
+const PRESET_IMPORTS = {
+    GraphQL: [
+        `import { ApolloServer } from "@apollo/server";`,
+        `import { expressMiddleware } from "@as-integrations/express5";`,
+        `import { typeDefs, resolvers } from "./graphql/schema";`,
+    ].join("\n"),
+};
+/**
+ * Per-preset runtime dependencies. The base application template ships only
+ * express + framework packages; each preset declares exactly which optional
+ * middleware packages it needs so scaffolded projects stay lean.
+ *
+ * Versions are pinned with `^` ranges matching the middleware-resolver
+ * registry expectations in `@expressots/core`.
+ */
+const PRESET_DEPENDENCIES = {
+    API: {
+        dependencies: {
+            compression: "^1.8.1",
+            cors: "^2.8.6",
+            "express-rate-limit": "^8.5.1",
+            helmet: "^8.1.0",
+        },
+        devDependencies: {
+            "@types/compression": "^1.7.5",
+            "@types/cors": "^2.8.17",
+        },
+    },
+    Web: {
+        dependencies: {
+            compression: "^1.8.1",
+            "cookie-parser": "^1.4.7",
+            cors: "^2.8.6",
+            helmet: "^8.1.0",
+        },
+        devDependencies: {
+            "@types/compression": "^1.7.5",
+            "@types/cookie-parser": "^1.4.8",
+            "@types/cors": "^2.8.17",
+        },
+    },
+    GraphQL: {
+        dependencies: {
+            "@apollo/server": "^5.5.1",
+            "@as-integrations/express5": "^1.1.2",
+            compression: "^1.8.1",
+            cors: "^2.8.6",
+            graphql: "^16.14.0",
+            helmet: "^8.1.0",
+        },
+        devDependencies: {
+            "@types/compression": "^1.7.5",
+            "@types/cors": "^2.8.17",
+        },
+    },
+    Microservice: {
+        dependencies: {
+            compression: "^1.8.1",
+        },
+        devDependencies: {
+            "@types/compression": "^1.7.5",
+        },
+    },
+    Minimal: {},
+};
 /**
  * Apply the selected middleware preset to the generated app.ts
  */
@@ -219,10 +299,101 @@ function applyMiddlewarePreset(directory, preset) {
     const presetName = presetMatch ? presetMatch[1] : "API";
     const presetCode = PRESET_CODE[presetName] || PRESET_CODE["API"];
     let content = node_fs_1.default.readFileSync(appTsPath, "utf-8");
+    // Inject preset-specific imports after the existing import block.
+    // Match the first blank line (handles both LF and CRLF endings).
+    const extraImports = PRESET_IMPORTS[presetName];
+    if (extraImports) {
+        const eol = content.includes("\r\n") ? "\r\n" : "\n";
+        content = content.replace(new RegExp(`${eol}${eol}`), `${eol}${extraImports}${eol}${eol}`);
+    }
     // Replace the placeholder with the preset code
     content = content.replace(/\/\/ __MIDDLEWARE_PRESET_PLACEHOLDER__/, presetCode);
     node_fs_1.default.writeFileSync(appTsPath, content, "utf-8");
 }
+/**
+ * GraphQL schema scaffold content. Provides sample typeDefs and resolvers
+ * so the generated project has a working `/graphql` endpoint out of the box.
+ */
+const GRAPHQL_SCHEMA_CONTENT = `export const typeDefs = \`#graphql
+    type Query {
+        hello: String!
+        health: HealthStatus!
+    }
+
+    type Mutation {
+        echo(message: String!): EchoResponse!
+    }
+
+    type HealthStatus {
+        status: String!
+        timestamp: String!
+        uptime: Float!
+    }
+
+    type EchoResponse {
+        message: String!
+        receivedAt: String!
+    }
+\`;
+
+export const resolvers = {
+    Query: {
+        hello: () => "Hello from ExpressoTS GraphQL!",
+        health: () => ({
+            status: "ok",
+            timestamp: new Date().toISOString(),
+            uptime: process.uptime(),
+        }),
+    },
+    Mutation: {
+        echo: (_: unknown, { message }: { message: string }) => ({
+            message,
+            receivedAt: new Date().toISOString(),
+        }),
+    },
+};
+`;
+/**
+ * Create additional source files required by specific presets.
+ * For example, the GraphQL preset ships a starter schema + resolvers.
+ */
+function createPresetFiles(directory, preset) {
+    const presetMatch = preset.match(/^(\w+) ::/);
+    const presetName = presetMatch ? presetMatch[1] : "API";
+    if (presetName === "GraphQL") {
+        const graphqlDir = node_path_1.default.join(directory, "src", "graphql");
+        if (!node_fs_1.default.existsSync(graphqlDir)) {
+            node_fs_1.default.mkdirSync(graphqlDir, { recursive: true });
+        }
+        node_fs_1.default.writeFileSync(node_path_1.default.join(graphqlDir, "schema.ts"), GRAPHQL_SCHEMA_CONTENT, "utf-8");
+    }
+}
+/**
+ * Inject preset-specific dependencies into the scaffolded project's
+ * package.json **before** `npm install` runs, so everything resolves
+ * in a single install step.
+ */
+function injectPresetDependencies(directory, preset) {
+    const pkgPath = node_path_1.default.join(directory, "package.json");
+    if (!node_fs_1.default.existsSync(pkgPath))
+        return;
+    const presetMatch = preset.match(/^(\w+) ::/);
+    const presetName = presetMatch ? presetMatch[1] : "API";
+    const presetDeps = PRESET_DEPENDENCIES[presetName];
+    if (!presetDeps)
+        return;
+    const pkg = JSON.parse(node_fs_1.default.readFileSync(pkgPath, "utf-8"));
+    if (presetDeps.dependencies) {
+        pkg.dependencies = { ...pkg.dependencies, ...presetDeps.dependencies };
+    }
+    if (presetDeps.devDependencies) {
+        pkg.devDependencies = {
+            ...pkg.devDependencies,
+            ...presetDeps.devDependencies,
+        };
+    }
+    node_fs_1.default.writeFileSync(pkgPath, JSON.stringify(pkg, null, 4) + "\n", "utf-8");
+}
 /**
  * Enable local template mode for testing.
  * Opt-in via `EXPRESSOTS_DEV=1` and `EXPRESSOTS_USE_LOCAL_TEMPLATES=1`.
@@ -244,18 +415,101 @@ const SKIP_INSTALL_FOR_TESTING = process.env.EXPRESSOTS_DEV === "1" &&
  * For production: this will be replaced with the actual path
  */
 const LOCAL_TEMPLATES_PATH = node_path_1.default.resolve(__dirname, "../../../templates");
+/**
+ * Optional override for the templates ref/tag.
+ *
+ * Useful during the preview window before the matching `vX.Y.Z` tag exists
+ * on `expressots/templates`. Setting `EXPRESSOTS_TEMPLATE_REF=feature/v4.0`
+ * makes `expressots new` clone from that branch instead of the version tag.
+ *
+ * This is intentionally NOT gated by `EXPRESSOTS_DEV`: even an installed
+ * CLI consumer can opt into a custom ref to test pre-release scaffolds.
+ */
+const TEMPLATE_REF_OVERRIDE = process.env.EXPRESSOTS_TEMPLATE_REF?.trim() || "";
+/**
+ * Resolve the degit ref to use when fetching a template.
+ *
+ * Priority:
+ *  1. Explicit override via `EXPRESSOTS_TEMPLATE_REF`
+ *  2. The version-pinned tag matching this CLI build (`v${BUNDLE_VERSION}`)
+ */
+function resolveTemplateRef() {
+    if (TEMPLATE_REF_OVERRIDE)
+        return TEMPLATE_REF_OVERRIDE;
+    return `v${cli_1.BUNDLE_VERSION}`;
+}
+/**
+ * Build the full degit URL for a given template folder.
+ */
+function buildTemplateRepo(templateFolder, ref) {
+    return `expressots/templates/${templateFolder}#${ref}`;
+}
+/**
+ * Detect whether the running CLI is a preview build (e.g.
+ * `4.0.0-preview.3`). During the preview window the matching templates tag
+ * may not yet exist on GitHub, so we allow a soft fallback to the active
+ * release branch.
+ */
+function isPreviewBuild() {
+    return /-(?:preview|alpha|beta|rc)\b/i.test(cli_1.BUNDLE_VERSION);
+}
+/**
+ * Fallback ref used when the primary ref is missing AND we are running a
+ * preview build. Matches the framework's working branch.
+ */
+const PREVIEW_FALLBACK_REF = "feature/v4.0";
+/**
+ * Clone a template from the public `expressots/templates` repo via degit.
+ *
+ * On `MISSING_REF` we attempt one graceful retry against the preview
+ * fallback branch — this keeps `npx @expressots/cli@next new` usable during
+ * the window between a CLI publish and the matching templates-tag push.
+ * For non-preview builds we let the error propagate so the user gets a
+ * loud, accurate diagnostic.
+ */
+async function cloneFromGitHub({ templateFolder, targetDir, progressBar, }) {
+    const primaryRef = resolveTemplateRef();
+    const primaryRepo = buildTemplateRepo(templateFolder, primaryRef);
+    try {
+        await (0, degit_1.default)(primaryRepo, { force: false }).clone(targetDir);
+        progressBar.update(30, { doing: "Template ready" });
+        return;
+    }
+    catch (err) {
+        const isMissingRef = err?.code === "MISSING_REF";
+        const canFallback = isMissingRef && !TEMPLATE_REF_OVERRIDE && isPreviewBuild();
+        if (!canFallback)
+            throw err;
+        // Tag for this preview hasn't been pushed yet; transparently retry
+        // against the working branch and surface a one-line warning so the
+        // user knows what they actually got. Written to stdout while the bar
+        // renders on stderr, so the streams do not interfere.
+        console.log(chalk_1.default.yellow(`\n⚠  Templates tag "${primaryRef}" not found on GitHub yet — falling back to "${PREVIEW_FALLBACK_REF}". ` +
+            `Set EXPRESSOTS_TEMPLATE_REF=<branch-or-tag> to override.`));
+        const fallbackRepo = buildTemplateRepo(templateFolder, PREVIEW_FALLBACK_REF);
+        await (0, degit_1.default)(fallbackRepo, { force: false }).clone(targetDir);
+        progressBar.update(30, { doing: "Template ready (fallback ref)" });
+    }
+}
 /**
  * Main project creation form
  */
 const projectForm = async (projectName, args) => {
     let answer;
-    const [packageManager, template, directory, preset] = args;
+    const [packageManager, template, directory, preset, events] = args;
     if (packageManager && template) {
+        const resolvedPreset = preset ??
+            (template === "application"
+                ? "api"
+                : undefined);
         answer = {
             name: projectName,
             packageManager: packageManager,
             template: Template[template],
-            preset: preset ? MiddlewarePreset[preset] : undefined,
+            preset: resolvedPreset
+                ? MiddlewarePreset[resolvedPreset]
+                : undefined,
+            events: events,
             confirm: true,
         };
     }
@@ -293,6 +547,7 @@ const projectForm = async (projectName, args) => {
         ]);
         // Only show preset selection for Application template
         let presetAnswer = {};
+        let eventsAnswer = {};
         if (baseAnswers.template.startsWith("Application")) {
             presetAnswer = await inquirer_1.default.prompt([
                 {
@@ -308,6 +563,19 @@ const projectForm = async (projectName, args) => {
                     ],
                 },
             ]);
+            // Opt-in to the type-safe Event Bus example. Defaults to No
+            // so the API/Web/GraphQL/etc. presets stay focused on what
+            // the user actually asked for. Picking Yes swaps the
+            // scaffold to `application-with-events` (extra event class
+            // + handler + `setupEventSystemForExpress` wiring).
+            eventsAnswer = await inquirer_1.default.prompt([
+                {
+                    type: "confirm",
+                    name: "events",
+                    message: "Include the type-safe Event Bus example? (adds a sample event + handler)",
+                    default: false,
+                },
+            ]);
         }
         const confirmAnswer = await inquirer_1.default.prompt([
             {
@@ -320,6 +588,7 @@ const projectForm = async (projectName, args) => {
         answer = {
             ...baseAnswers,
             ...presetAnswer,
+            ...eventsAnswer,
             ...confirmAnswer,
         };
     }
@@ -339,15 +608,33 @@ const projectForm = async (projectName, args) => {
             process.exit(1);
         }
         await checkIfPackageManagerExists(answer.packageManager);
-        console.log("\n");
+        process.stdout.write(`\n  ${chalk_1.default.dim("Creating")} ${chalk_1.default.bold.green(answer.name)}\n\n`);
+        const termCols = typeof process.stdout.columns === "number" &&
+            process.stdout.columns > 0
+            ? process.stdout.columns
+            : 80;
+        const barsize = Math.max(20, Math.min(40, termCols - 22));
         const progressBar = new cli_progress_1.SingleBar({
-            format: "Progress |" +
-                chalk_1.default.green("{bar}") +
-                "| {percentage}% || {doing}",
+            format: "  {bar}  " +
+                chalk_1.default.bold("{percentage}") +
+                chalk_1.default.dim("%") +
+                "  " +
+                chalk_1.default.dim("{doing}"),
+            barCompleteChar: "\u2588",
+            barIncompleteChar: "\u2591",
+            formatBar: (progress, options) => {
+                const completeSize = Math.round(progress * (options.barsize ?? barsize));
+                const incompleteSize = (options.barsize ?? barsize) - completeSize;
+                return (chalk_1.default.green("\u2588".repeat(completeSize)) +
+                    chalk_1.default.dim("\u2591".repeat(incompleteSize)));
+            },
+            barsize,
             hideCursor: true,
-        }, cli_progress_1.Presets.rect);
+            clearOnComplete: false,
+            linewrap: false,
+        }, cli_progress_1.Presets.legacy);
         progressBar.start(100, 0, {
-            doing: "Creating project",
+            doing: "Fetching template",
         });
         // Extract template name from selection
         const templateMatch = answer.template.match(/(.*) ::/);
@@ -357,7 +644,15 @@ const projectForm = async (projectName, args) => {
             process.exit(1);
         }
         const templateName = templateMatch[1];
-        const templateFolder = TEMPLATE_FOLDERS[templateName];
+        // The "Application with Events" template is no longer a top-level
+        // choice. When the user opts into events on the Application track
+        // (or passes `--events`), swap the folder so we still pull from
+        // `application-with-events`. The folder split is preserved on disk
+        // for now so we keep two minimal sources of truth.
+        let templateFolder = TEMPLATE_FOLDERS[templateName];
+        if (templateName === "Application" && answer.events) {
+            templateFolder = TEMPLATE_FOLDERS["Application with Events"];
+        }
         if (!templateFolder) {
             progressBar.stop();
             (0, cli_ui_1.printError)(`Unknown template: ${templateName}`, "new");
@@ -376,23 +671,47 @@ const projectForm = async (projectName, args) => {
                 node_fs_1.default.mkdirSync(answer.name, { recursive: true });
                 // Copy template files
                 copyDirectorySync(localTemplatePath, answer.name);
-                progressBar.update(30, { doing: "Template copied" });
+                progressBar.update(30, { doing: "Template ready" });
             }
             else {
                 // GITHUB MODE (production)
-                // Pinned to the v4.0.0 GA tag of the templates repo so a
-                // CLI shipped at v4.0.0 keeps working even if `main` moves.
-                const repo = `expressots/templates/${templateFolder}#v4.0.0-preview.1`;
-                const emitter = (0, degit_1.default)(repo);
-                await emitter.clone(answer.name);
-                progressBar.update(30, { doing: "Template cloned" });
+                // Pinned to the templates tag matching this CLI's published
+                // version (e.g. CLI 4.0.0-preview.3 -> templates/v4.0.0-preview.3).
+                // BUNDLE_VERSION reads from this package's package.json, so a
+                // CLI release and its templates tag move together.
+                await cloneFromGitHub({
+                    templateFolder,
+                    targetDir: answer.name,
+                    progressBar,
+                });
             }
         }
         catch (err) {
             console.log("\n");
-            (0, cli_ui_1.printError)("Project already exists or Folder is not empty", answer.name);
+            // Surface the real failure cause so users can self-diagnose
+            // instead of guessing at "folder not empty" every time.
+            const msg = err?.message ? String(err.message) : String(err);
+            const code = err?.code ? ` [${err.code}]` : "";
+            if (err?.code === "DEST_NOT_EMPTY" ||
+                /already exists|not empty/i.test(msg)) {
+                (0, cli_ui_1.printError)(`Target folder "${answer.name}" already exists or is not empty`, answer.name);
+            }
+            else {
+                (0, cli_ui_1.printError)(`Failed to scaffold project${code}: ${msg}`, answer.name);
+            }
             process.exit(1);
         }
+        // Apply preset files + placeholder substitution BEFORE install so
+        // that a failed/skipped install still leaves the user with a
+        // runnable scaffold (the middleware preset placeholder must not
+        // leak into src/app.ts as a literal comment).
+        if (answer.preset &&
+            (templateFolder === "application" ||
+                templateFolder === "application-with-events")) {
+            injectPresetDependencies(answer.name, answer.preset);
+            createPresetFiles(answer.name, answer.preset);
+            applyMiddlewarePreset(answer.name, answer.preset);
+        }
         if (SKIP_INSTALL_FOR_TESTING) {
             progressBar.update(90, {
                 doing: "Skipping install (testing mode)",
@@ -411,11 +730,7 @@ const projectForm = async (projectName, args) => {
         // Progress should already be at 90% from packageManagerInstall
         // Only update if we skipped installation
         if (!SKIP_INSTALL_FOR_TESTING) {
-            progressBar.update(90, { doing: "Finalizing project" });
-        }
-        // Apply middleware preset for Application template
-        if (answer.preset && templateFolder === "application") {
-            applyMiddlewarePreset(answer.name, answer.preset);
+            progressBar.update(90, { doing: "Finalizing" });
         }
         (0, change_package_info_1.changePackageName)({
             directory: answer.name,

package/bin/profile/cli.d.ts

@@ -1,4 +1,4 @@
 import { CommandModule } from "yargs";
-type CommandModuleArgs = {};
+type CommandModuleArgs = Record<string, never>;
 declare const profileCommand: () => CommandModule<CommandModuleArgs, any>;
 export { profileCommand };

package/bin/profile/cli.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.profileCommand = void 0;
 const form_1 = require("./form");
+const cli_ui_1 = require("../utils/cli-ui");
 const profileCommand = () => {
     return {
         command: "profile <action> [target]",
@@ -84,7 +85,8 @@ const profileCommand = () => {
                     await (0, form_1.showProfileReport)(options);
                     break;
                 default:
-                    console.log(`Unknown action: ${action}`);
+                    (0, cli_ui_1.printError)(`Unknown action: ${action}`, "profile");
+                    process.exit(1);
             }
         },
     };

package/bin/profile/form.js

@@ -10,11 +10,12 @@ const chalk_1 = __importDefault(require("chalk"));
 const dockerfile_analyzer_1 = require("./analyzers/dockerfile-analyzer");
 const image_analyzer_1 = require("./analyzers/image-analyzer");
 const optimizers_1 = require("./optimizers");
+const cli_ui_1 = require("../utils/cli-ui");
 /**
  * Profile a Dockerfile for issues and recommendations
  */
 async function profileContainer(options) {
-    console.log(chalk_1.default.cyan("\n🔍 ExpressoTS Container Profiler\n"));
+    (0, cli_ui_1.printSection)("🔍 ExpressoTS Container Profiler");
     const cwd = process.cwd();
     const dockerfilePath = path_1.default.join(cwd, options.dockerfile);
     if (!fs_1.default.existsSync(dockerfilePath)) {
@@ -32,7 +33,7 @@ exports.profileContainer = profileContainer;
  * Profile a built Docker image
  */
 async function profileImage(options) {
-    console.log(chalk_1.default.cyan("\n🔍 ExpressoTS Image Profiler\n"));
+    (0, cli_ui_1.printSection)("🔍 ExpressoTS Image Profiler");
     if (!options.target) {
         console.log(chalk_1.default.red("Error: Please specify an image name."));
         console.log(chalk_1.default.gray("Usage: expressots profile image <image-name>"));
@@ -71,7 +72,7 @@ exports.profileImage = profileImage;
  * Generate and optionally apply optimizations
  */
 async function optimizeContainer(options) {
-    console.log(chalk_1.default.cyan("\n⚡ ExpressoTS Container Optimizer\n"));
+    (0, cli_ui_1.printSection)("⚡ ExpressoTS Container Optimizer");
     const cwd = process.cwd();
     const dockerfilePath = path_1.default.join(cwd, options.dockerfile);
     if (!fs_1.default.existsSync(dockerfilePath)) {
@@ -110,7 +111,7 @@ exports.optimizeContainer = optimizeContainer;
  * Show a comprehensive profile report
  */
 async function showProfileReport(options) {
-    console.log(chalk_1.default.cyan("\n📊 ExpressoTS Container Profile Report\n"));
+    (0, cli_ui_1.printSection)("📊 ExpressoTS Container Profile Report");
     const cwd = process.cwd();
     const dockerfilePath = path_1.default.join(cwd, options.dockerfile);
     if (!fs_1.default.existsSync(dockerfilePath)) {

package/bin/providers/create/form.js

@@ -7,9 +7,44 @@ exports.createExternalProvider = void 0;
 const chalk_1 = __importDefault(require("chalk"));
 const degit_1 = __importDefault(require("degit"));
 const inquirer_1 = __importDefault(require("inquirer"));
+const cli_1 = require("../../cli");
 const center_text_1 = require("../../utils/center-text");
 const change_package_info_1 = require("../../utils/change-package-info");
 const cli_ui_1 = require("../../utils/cli-ui");
+/**
+ * Override the templates ref/tag, mirroring `EXPRESSOTS_TEMPLATE_REF` in the
+ * `new` command. Lets users target a branch (e.g. `feature/v4.0`) before the
+ * matching version tag has been pushed.
+ */
+const TEMPLATE_REF_OVERRIDE = process.env.EXPRESSOTS_TEMPLATE_REF?.trim() || "";
+const PREVIEW_FALLBACK_REF = "feature/v4.0";
+function isPreviewBuild() {
+    return /-(?:preview|alpha|beta|rc)\b/i.test(cli_1.BUNDLE_VERSION);
+}
+function resolveProviderRef() {
+    if (TEMPLATE_REF_OVERRIDE)
+        return TEMPLATE_REF_OVERRIDE;
+    return `v${cli_1.BUNDLE_VERSION}`;
+}
+async function cloneProviderTemplate(targetDir) {
+    const primaryRef = resolveProviderRef();
+    const primaryRepo = `expressots/templates/provider#${primaryRef}`;
+    try {
+        await (0, degit_1.default)(primaryRepo, { force: false }).clone(targetDir);
+        return;
+    }
+    catch (err) {
+        const isMissingRef = err?.code === "MISSING_REF";
+        const canFallback = isMissingRef && !TEMPLATE_REF_OVERRIDE && isPreviewBuild();
+        if (!canFallback)
+            throw err;
+        console.log(chalk_1.default.yellow(`\n⚠  Templates tag "${primaryRef}" not found on GitHub yet — falling back to "${PREVIEW_FALLBACK_REF}". ` +
+            `Set EXPRESSOTS_TEMPLATE_REF=<branch-or-tag> to override.`));
+        await (0, degit_1.default)(`expressots/templates/provider#${PREVIEW_FALLBACK_REF}`, {
+            force: false,
+        }).clone(targetDir);
+    }
+}
 async function printInfo(providerName) {
     console.log("\n");
     console.log("🐎 Provider", chalk_1.default.green(providerName), "created successfully!");
@@ -39,9 +74,15 @@ const createExternalProvider = async (provider) => {
             ]);
         }
         try {
-            // Pinned to the v4.0.0 GA tag, same policy as `expressots new`.
-            const emitter = (0, degit_1.default)(`expressots/templates/provider#v4.0.0-preview.1`);
-            await emitter.clone(providerInfo.providerName);
+            // Pinned to the templates tag matching this CLI's published version,
+            // same policy as `expressots new`. BUNDLE_VERSION reads from the
+            // CLI's own package.json so the ref always tracks the release.
+            //
+            // Mirrors the preview-fallback logic in `new/form.ts`: during the
+            // preview window the matching `vX.Y.Z` tag may not yet be on
+            // `expressots/templates`, so we soft-fall back to the active
+            // release branch and warn rather than failing opaquely.
+            await cloneProviderTemplate(providerInfo.providerName);
             (0, change_package_info_1.changePackageName)({
                 directory: providerInfo.providerName,
                 name: providerInfo.providerName,
@@ -51,7 +92,15 @@ const createExternalProvider = async (provider) => {
         }
         catch (err) {
             console.log("\n");
-            (0, cli_ui_1.printError)("Project already exists or Folder is not empty", "");
+            const msg = err?.message ? String(err.message) : String(err);
+            const code = err?.code ? ` [${err.code}]` : "";
+            if (err?.code === "DEST_NOT_EMPTY" ||
+                /already exists|not empty/i.test(msg)) {
+                (0, cli_ui_1.printError)(`Target folder "${providerInfo.providerName}" already exists or is not empty`, "");
+            }
+            else {
+                (0, cli_ui_1.printError)(`Failed to scaffold provider${code}: ${msg}`, "");
+            }
             reject(err);
         }
     });

package/bin/studio/cli.js

@@ -11,6 +11,7 @@ const chalk_1 = __importDefault(require("chalk"));
 const ora_1 = __importDefault(require("ora"));
 const fs_1 = require("fs");
 const path_1 = require("path");
+const cli_1 = require("../cli");
 const safe_spawn_1 = require("../utils/safe-spawn");
 /**
  * Check if @expressots/studio is installed
@@ -33,19 +34,24 @@ async function installStudio() {
     try {
         const hasYarn = (0, fs_1.existsSync)((0, path_1.resolve)(process.cwd(), "yarn.lock"));
         const hasPnpm = (0, fs_1.existsSync)((0, path_1.resolve)(process.cwd(), "pnpm-lock.yaml"));
+        // Pin the studio install to the same minor as the running CLI so
+        // `expressots studio` from a preview-N CLI fetches a matching
+        // preview-N studio. Falls back to a caret on the major if the CLI
+        // version isn't a valid prerelease (defensive).
+        const studioSpec = `@expressots/studio@^${cli_1.BUNDLE_VERSION}`;
         let pkgManager;
         let args;
         if (hasPnpm) {
             pkgManager = "pnpm";
-            args = ["add", "-D", "@expressots/studio"];
+            args = ["add", "-D", studioSpec];
         }
         else if (hasYarn) {
             pkgManager = "yarn";
-            args = ["add", "-D", "@expressots/studio"];
+            args = ["add", "-D", studioSpec];
         }
         else {
             pkgManager = "npm";
-            args = ["install", "-D", "@expressots/studio"];
+            args = ["install", "-D", studioSpec];
         }
         // `safeSpawnSync` (cross-spawn) resolves the Windows `.cmd` shim
         // and properly escapes argv for cmd.exe. The argv here is a