@clubedge/create-clubedge-app 0.46.0 → 0.47.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.47.0
+
+- **Starter v0.31.0** by default (#183). Its template schema is still 6. The [Starter's release notes](https://github.com/Clubedge/clubedge-starter/releases/tag/v0.31.0) cover:
+  - deploying React + Vite and its API to Cloudflare (`--deploy cloudflare`), which has not yet run on an account with Workers Paid;
+  - downloads by byte range from storage, which browsers ask for to play audio and video;
+  - Supabase sessions that the Hono API verifies itself;
+  - fixes to the APIs' CORS and to SMTP sends that never answer;
+  - browser tests in Chromium, Firefox, and WebKit.
+- **On Windows, an argument can no longer run a second command or expand a variable** (#176). The CLI ran commands through cmd.exe as one line, where `%VAR%` is expanded inside quotes, a line break ends the command, and a quote inside an argument can leave `&` and `|` outside the quotes. No argument from outside reached these commands, so this closes the gap before one does:
+  - A program (`.exe`, `.com`) now starts directly, with no shell, so `git`, `node`, `docker`, and `uv` no longer go through cmd.exe.
+  - A batch file (`.cmd`, `.bat`), such as the npm shims for `pnpm` and `npx`, still needs cmd.exe. Each argument is quoted the way Windows programs split their command line, then escaped for both of cmd.exe's readings. An argument with a line break is refused.
+- **Windows device names are refused as project directories** (#169, #171): `CON`, `PRN`, `AUX`, `NUL`, `COM1` to `COM9`, and `LPT1` to `LPT9`, with or without an extension, which on Windows could create a folder that can't be deleted. The CLI checks the project's own name and each parent folder it would create, in the prompt and in the MCP server's `create_project` too. Folders that already exist are left alone.
+- **The browser opens web addresses only** (#175). Commands that open a page, such as `deploy`, `neon`, and `try`, hand the system's opener only an `http://` or `https://` address with a host, and open nothing otherwise.
+- **`create_project` reports progress over MCP** (#178) while it installs dependencies. A client that sends a progress token gets a notification when each install starts, every 5 seconds while it runs, and when it ends or fails, so a client that resets its timeout on progress keeps waiting. A client that sends none gets the same result as before.
+- **Sponsors** (#181, #182): the README has a Sponsors section. [Neon](https://neon.com) supports Clubedge Starter through its Open Source Program.
+- CI runs generated projects' browser checks in Chromium, by name (#180), since the Starter now has three browser projects.
+- `@modelcontextprotocol/server` 2.4.0 or newer (#173), vitest 5.1.0 (#174), and astral-sh/setup-uv 10.3.3 in CI (#172).
+
+## 0.46.1
+
+- **Starter v0.30.1** by default (#167). Its template schema is still 6. The [Starter's release notes](https://github.com/Clubedge/clubedge-starter/releases/tag/v0.30.1) cover:
+  - the native app (`--mobile expo`) reaching its API again: since v0.29.0, each of its calls to the API threw after the API had answered, so the account never loaded, and saving a name or deleting the account failed;
+  - getting the fix to installed apps: a new build in the stores, then `APP_MINIMUM_VERSION` on the API, which sends older installs to the update screen, or an over-the-air update with `--ota eas`;
+  - end-to-end tests of both mobile apps on an Android emulator;
+  - Expo SDK 58's latest patch versions.
+
 ## 0.46.0
 
 - **Add and remove the apps installed on devices** (#161), so a project created without them can take them later, and drop them again, without starting over: `pnpm clubedge add mobile expo` for the native app, `pnpm clubedge add shell capacitor` for the shell that packages the website, and `pnpm clubedge remove mobile` or `pnpm clubedge remove shell`. The shell needs Starter v0.27.0 or later, and the native app v0.28.0.

package/README.md

@@ -48,6 +48,8 @@ cwd = "D:/path/to/workspace"
 
 The MCP server is included in the same package and uses the CLI's bundled Starter and compatibility rules. Its create tool only writes beneath the configured working directory and refuses a non-empty destination.
 
+With `install_dependencies`, `create_project` answers once `pnpm install` and each app's own install, such as `uv sync` for a FastAPI API, have finished, which can take minutes. A client that sends a progress token with the call (`_meta.progressToken`) gets a `notifications/progress` message when each install starts, every 5 seconds while it runs, and when it ends or fails, such as `pnpm install: running for 40s`. Clients that reset their request timeout on progress, as the MCP TypeScript SDK does with `resetTimeoutOnProgress`, then wait for as long as the installs take. `progress` counts the notifications sent and there is no `total`, since how far along an install is isn't known. Without a token nothing is sent, and the result is the same either way.
+
 ### Agent skill
 
 The npm package includes the Agent Skill at [`skills/clubedge-starter/SKILL.md`](skills/clubedge-starter/SKILL.md). Download and extract the package in PowerShell:
@@ -230,7 +232,7 @@ Options:
   -v, --version           Show the CLI version
 ```
 
-The target directory must be empty or not exist. The CLI never deletes or overwrites existing files, and if scaffolding fails it removes whatever it wrote, so a failed run leaves nothing behind.
+The target directory must be empty or not exist, and its name can't be one Windows reserves for a device, such as `CON`, `NUL`, or `COM1`, even on macOS or Linux; the same goes for any folder the CLI creates above it. The CLI never deletes or overwrites existing files, and if scaffolding fails it removes whatever it wrote, so a failed run leaves nothing behind.
 
 ```sh
 # Preview the files and edits without writing anything
@@ -243,7 +245,7 @@ pnpm dlx @clubedge/create-clubedge-app my-app --yes --no-git --framework tanstac
 pnpm dlx @clubedge/create-clubedge-app my-app --ref main
 
 # Reproduce a specific Starter release or commit
-pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.30.0
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.31.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -264,7 +266,7 @@ pnpm clubedge add mobile expo                               # the native app; ad
 pnpm clubedge remove mobile
 pnpm dlx @clubedge/create-clubedge-app add infra local --dry-run
 pnpm dlx @clubedge/create-clubedge-app@latest upgrade        # to the newest CLI's Starter release
-pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.30.0 # or a specific tag, branch, or commit
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.31.0 # or a specific tag, branch, or commit
 ```
 
 The CLI renders the project twice, from the Starter commit and modules recorded in your `package.json` and from the new state, and merges the difference into your project. The new state has other modules for `add` and `remove`, and the newer Starter with the same modules for `upgrade`. Modules a newer Starter introduces start as `none` where possible, so an upgrade never adds a service on its own.
@@ -413,27 +415,27 @@ Projects created with `--infra neon` also have `.github/workflows/preview.yml`,
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.46.0
+create-clubedge-app v0.47.0
         |
         v
-Clubedge Starter v0.30.0
-commit 4d341955bd13cb170c7385acb745c3d374259897
+Clubedge Starter v0.31.0
+commit e6c47d7b8ec153443ee35abab7fc61d37f55e36a
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.46.0` | `clubedge-starter@v0.30.0` | The CLI's required, tested default |
+| `create-clubedge-app@0.47.0` | `clubedge-starter@v0.31.0` | The CLI's required, tested default |
 
 This means the same CLI version always scaffolds the same Starter revision by default. The CLI does not silently follow Starter `main`.
 
-The `v0.30.0` tag is expected to resolve to commit
-`4d341955bd13cb170c7385acb745c3d374259897`. The CLI verifies this before
+The `v0.31.0` tag is expected to resolve to commit
+`e6c47d7b8ec153443ee35abab7fc61d37f55e36a`. The CLI verifies this before
 scaffolding with the default reference and fails rather than silently using a
 moved tag.
 
-When the Starter changes, its maintainers first publish a new versioned release, such as `v0.30.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
+When the Starter changes, its maintainers first publish a new versioned release, such as `v0.31.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
 
 Every generated project records its CLI version, Starter repository, Starter ref, Starter commit, framework, and modules in `package.json` and `README.md`.
 
@@ -488,7 +490,7 @@ CI packs the CLI with `npm pack`, scaffolds clean projects from the packed tarba
 1. Make and validate changes in `clubedge-starter`.
 2. Run lint, typecheck, unit tests, browser tests, and production build.
 3. Update the Starter package versions.
-4. Commit `main`, create a release tag such as `v0.30.0`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.31.0`, and publish the Starter release.
 
 ### CLI maintainers
 
@@ -545,6 +547,22 @@ Each phase ends with a Starter release and a CLI release pinned to it. The full
 | 0.44.0 | v0.28.0 | Starter v0.28.0: the native app with Expo (`--mobile expo`, template schema 6); projects without a website (`--framework none`), with template rules; audit exceptions per stack |
 | 0.45.0 | v0.29.0 | Starter v0.29.0: an update policy for installed apps, a new design for the native app, and clean splash screens; `package.json` merged by key |
 | 0.46.0 | v0.30.0 | Add and remove the mobile apps in an existing project; Starter v0.30.0: store releases, push notifications, and over-the-air updates; module options' `dependencies` |
+| 0.47.0 | v0.31.0 | Starter v0.31.0: deploying to Cloudflare (`--deploy cloudflare`), downloads by byte range, and browser tests in three engines; on Windows, arguments that can't start a second command and device names refused as project directories; install progress over MCP |
+
+## Sponsors
+
+<!-- To add a sponsor: put its light and dark logos in .github/assets/sponsors/ and copy the entry below. -->
+
+<p>
+  <a href="https://neon.com">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Clubedge/create-clubedge-app/main/.github/assets/sponsors/neon-dark.svg">
+      <img src="https://raw.githubusercontent.com/Clubedge/create-clubedge-app/main/.github/assets/sponsors/neon-light.svg" alt="Neon" height="36">
+    </picture>
+  </a>
+</p>
+
+[Neon](https://neon.com) supports Clubedge Starter through its Open Source Program.
 
 ## Community
 

package/dist/core/execute.js

@@ -1,15 +1,29 @@
 import { constants } from "node:fs";
 import { copyFile, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
-import { dirname, join, parse } from "node:path";
+import { basename, dirname, join, parse } from "node:path";
 import { copyTemplateFiles, emptyDirectory, pathExists } from "../utils/fs.js";
+import { isReservedDeviceName } from "../utils/names.js";
 export class TargetError extends Error {
     name = "TargetError";
 }
-/** Refuses filesystem roots and non-empty directories. Never deletes or overwrites anything. */
+/** Refuses filesystem roots, reserved Windows device names, and non-empty directories. Never deletes or overwrites anything. */
 export async function assertTargetIsUsable(directory) {
     if (parse(directory).root === directory) {
         throw new TargetError("Choose a project subdirectory rather than a filesystem root.");
     }
+    // Check the project's own name and each missing parent that executePlan would create. A parent
+    // that already exists is left alone, such as a home folder named con on macOS.
+    let folder = directory;
+    while (true) {
+        const name = basename(folder);
+        if (isReservedDeviceName(name)) {
+            throw new TargetError(`"${name}" is a reserved device name on Windows. Choose another directory name.`);
+        }
+        const parent = dirname(folder);
+        if (parent === folder || (await pathExists(parent)))
+            break;
+        folder = parent;
+    }
     try {
         const entries = await readdir(directory);
         if (entries.length > 0)

package/dist/index.js

@@ -1,6 +1,6 @@
 import { cancel, confirm, intro, isCancel, log, outro, select, spinner, text } from "@clack/prompts";
 import { readFile } from "node:fs/promises";
-import { join, relative, resolve } from "node:path";
+import { basename, join, relative, resolve } from "node:path";
 import process from "node:process";
 import { parseCliArgs, UsageError } from "./cli/args.js";
 import { dim, helpText, showBanner } from "./cli/ui.js";
@@ -17,7 +17,7 @@ import { describeNewDatabase, neonCommand, provisionNeonDatabase } from "./neon.
 import { initializeGit } from "./steps/git.js";
 import { detectLauncher, detectPnpm, installDependencies } from "./steps/install.js";
 import { commandSucceeds, run } from "./utils/process.js";
-import { displayNameFromPackageName, packageNameFromDirectory } from "./utils/names.js";
+import { displayNameFromPackageName, isReservedDeviceName, packageNameFromDirectory } from "./utils/names.js";
 const minimumNode = [22, 12];
 export function assertSupportedNode(version = process.versions.node) {
     const [major = 0, minor = 0] = version.split(".").map(Number);
@@ -29,7 +29,15 @@ async function askProjectDirectory() {
     const value = await text({
         message: "Where should the new project be created?",
         placeholder: "my-app",
-        validate: (input) => (input?.trim() ? undefined : "Enter a project directory name."),
+        validate: (input) => {
+            const trimmed = input?.trim();
+            if (!trimmed)
+                return "Enter a project directory name.";
+            if (isReservedDeviceName(basename(trimmed))) {
+                return `"${basename(trimmed)}" is a reserved device name on Windows. Choose another directory name.`;
+            }
+            return undefined;
+        },
     });
     if (isCancel(value)) {
         cancel("Operation cancelled.");

package/dist/mcp-progress.js

@@ -0,0 +1,57 @@
+/**
+ * How often a running step reports progress. Clients that reset their request timeout on
+ * progress wait tens of seconds, so a few seconds between notifications keeps the call alive.
+ */
+const intervalMs = 5_000;
+/** A duration for a message: "45s", and "2m 5s" from a minute on. */
+function formatElapsed(milliseconds) {
+    const seconds = Math.round(milliseconds / 1000);
+    return seconds < 60 ? `${seconds}s` : `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
+}
+/**
+ * Progress notifications for the long steps of a tool call, such as `pnpm install`, which can
+ * outlast a client's request timeout. Only a client that sent a progress token with its request
+ * (`_meta.progressToken`) is notified; without one the steps run and nothing is sent.
+ */
+export function stepProgress(request) {
+    const token = request._meta?.progressToken;
+    // The protocol wants each value above the one before. How far along an install is isn't known,
+    // so the value counts the notifications sent, and no total is given.
+    let sent = 0;
+    const notify = async (message) => {
+        // A client that cancelled the call no longer knows the token.
+        if (token === undefined || request.signal.aborted)
+            return;
+        sent += 1;
+        try {
+            await request.notify({ method: "notifications/progress", params: { progressToken: token, progress: sent, message } });
+        }
+        catch {
+            // The client left or its transport closed. The step is not affected.
+        }
+    };
+    return {
+        async step(name, run) {
+            if (token === undefined)
+                return run();
+            const startedAt = Date.now();
+            const elapsed = () => formatElapsed(Date.now() - startedAt);
+            // Notifications are not awaited: a client that reads slowly must not hold the step up.
+            void notify(`${name}: started`);
+            const timer = setInterval(() => void notify(`${name}: running for ${elapsed()}`), intervalMs);
+            try {
+                const result = await run();
+                void notify(`${name}: finished in ${elapsed()}`);
+                return result;
+            }
+            catch (error) {
+                void notify(`${name}: failed after ${elapsed()}`);
+                throw error;
+            }
+            finally {
+                // Cleared however the step ends, so the timer never keeps the server running.
+                clearInterval(timer);
+            }
+        },
+    };
+}

package/dist/mcp-server.js

@@ -9,6 +9,7 @@ import { isOptionalSlot, readTemplateManifest } from "./core/manifest.js";
 import { neonSetupStep } from "./core/neon.js";
 import { createPlan, describePlan } from "./core/plan.js";
 import { resolveTemplateSource } from "./core/source.js";
+import { stepProgress } from "./mcp-progress.js";
 import { cliVersion, cliUrl, siteUrl } from "./package-info.js";
 import { initializeGit } from "./steps/git.js";
 import { detectPnpm, installDependencies } from "./steps/install.js";
@@ -202,7 +203,7 @@ function createServer() {
             initialize_git: z.boolean().default(false).describe("Initialize a Git repository after generating files."),
             install_dependencies: z.boolean().default(false).describe("Run pnpm install and declared secondary toolchain installs after generating files."),
         }),
-    }, async ({ directory, initialize_git, install_dependencies, ...options }) => withTemplate(async (source) => {
+    }, async ({ directory, initialize_git, install_dependencies, ...options }, ctx) => withTemplate(async (source) => {
         const target = await workspaceDestination(directory);
         const plan = await planProject(source, options, target, { git: initialize_git, install: install_dependencies });
         await executePlan(plan, source);
@@ -227,8 +228,11 @@ function createServer() {
                     : "Project created, but pnpm was not found. Install pnpm and run it in the project directory.");
             }
             else {
+                // Installs can outlast a client's request timeout. A client that sent a progress token
+                // hears from each one while it runs, and can keep waiting.
+                const progress = stepProgress(ctx.mcpReq);
                 try {
-                    await installDependencies(target, pnpm, [], mcpStdio);
+                    await progress.step([...pnpm, "install"].join(" "), () => installDependencies(target, pnpm, [], mcpStdio));
                     for (const { directory: appDirectory, app, toolchain } of plan.toolchains) {
                         const [check, ...checkArgs] = toolchain.check;
                         if (!(await commandSucceeds(check, checkArgs))) {
@@ -237,7 +241,7 @@ function createServer() {
                         }
                         const [command, ...args] = toolchain.install;
                         try {
-                            await run(command, args, resolve(target, appDirectory), mcpStdio);
+                            await progress.step(`${toolchain.install.join(" ")} in ${appDirectory}`, () => run(command, args, resolve(target, appDirectory), mcpStdio));
                         }
                         catch (error) {
                             warnings.push(`${app} dependencies did not install: ${error instanceof Error ? error.message : String(error)}`);

package/dist/utils/names.js

@@ -1,4 +1,15 @@
 import { basename } from "node:path";
+// Windows reserves these names (and the CONIN$/CONOUT$ console handles) for legacy devices,
+// in any case and regardless of extension, even though the Win32 namespace can bypass the
+// check and leave an undeletable directory behind. COM/LPT also reserve the ¹²³ superscript
+// digits Windows treats as equivalent to 1, 2, 3.
+const RESERVED_DEVICE_NAMES = /^(CON|PRN|AUX|NUL|CONIN\$|CONOUT\$|COM[0-9¹²³]|LPT[0-9¹²³])(\..*)?$/i;
+export function isReservedDeviceName(name) {
+    const dotIndex = name.indexOf(".");
+    const base = dotIndex === -1 ? name : name.slice(0, dotIndex);
+    const extension = dotIndex === -1 ? "" : name.slice(dotIndex);
+    return RESERVED_DEVICE_NAMES.test(base.replace(/ +$/, "") + extension);
+}
 export function packageNameFromDirectory(directory) {
     return (basename(directory)
         .toLowerCase()

package/dist/utils/open.js

@@ -1,7 +1,21 @@
 import { spawn } from "node:child_process";
 import process from "node:process";
+/** Only web URLs may reach an OS opener (which can otherwise launch local programs). */
+export function assertWebUrl(url) {
+    // Reject URL-parser fixups (backslashes, missing //, or surrounding whitespace)
+    // before passing the original value to a platform-specific command.
+    if (!/^https?:\/\//.test(url) || /[\\\s]/.test(url)) {
+        throw new Error("Refusing to open a non-web URL");
+    }
+    const parsed = new URL(url);
+    if ((parsed.protocol !== "http:" && parsed.protocol !== "https:") || !parsed.hostname) {
+        throw new Error("Refusing to open a non-web URL");
+    }
+    return parsed;
+}
 /** The command that opens a URL in the default browser on this platform. */
 export function openCommand(url, platform = process.platform) {
+    assertWebUrl(url);
     if (platform === "win32")
         return ["rundll32", ["url.dll,FileProtocolHandler", url]];
     if (platform === "darwin")
@@ -10,7 +24,14 @@ export function openCommand(url, platform = process.platform) {
 }
 /** Opens a URL in the default browser. Best effort: returns false when nothing could open it. */
 export async function openUrl(url) {
-    const [command, args] = openCommand(url);
+    let command;
+    let args;
+    try {
+        [command, args] = openCommand(url);
+    }
+    catch {
+        return false;
+    }
     return await new Promise((resolve) => {
         try {
             const child = spawn(command, args, { detached: true, stdio: "ignore" });

package/dist/utils/process.js

@@ -1,21 +1,105 @@
 import { spawn } from "node:child_process";
+import { statSync } from "node:fs";
 import { access } from "node:fs/promises";
 import { delimiter, isAbsolute, join, resolve } from "node:path";
 import process from "node:process";
+import { fileURLToPath } from "node:url";
 // Package manager shims on Windows are .cmd files, which need a shell to start.
 const useShell = process.platform === "win32";
-/** An argument as one word for cmd.exe: plain words as they are, anything else in double quotes. */
-export function quoteForCmd(argument) {
-    return /^[\w@+=:,./\\-]+$/.test(argument) ? argument : `"${argument.replaceAll('"', '""')}"`;
+/** An environment variable by name, whatever its case: Windows keeps Path as it was written. */
+function envValue(env, name) {
+    const key = Object.keys(env).find((candidate) => candidate.toUpperCase() === name);
+    return key === undefined ? undefined : env[key];
+}
+function isFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The file cmd.exe runs for a command: the path as given when it names a folder, else the first
+ * match in the current folder and then PATH's folders, each with PATHEXT's extensions in order
+ * unless the command already ends with one. Null when there is none.
+ */
+export function resolveForCmd(command, env = process.env, cwd = process.cwd()) {
+    const extensions = (envValue(env, "PATHEXT") ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean);
+    const named = extensions.some((extension) => command.toLowerCase().endsWith(extension.toLowerCase()));
+    const candidates = (base) => (named ? [base] : extensions.map((extension) => base + extension));
+    if (/[\\/:]/.test(command))
+        return candidates(resolve(cwd, command)).find(isFile) ?? null;
+    // A folder in PATH may be written in quotes.
+    const path = (envValue(env, "PATH") ?? "").split(delimiter).map((folder) => folder.replace(/^"(.*)"$/, "$1"));
+    const folders = [cwd, ...path.filter(Boolean)];
+    for (const folder of folders) {
+        const found = candidates(join(isAbsolute(folder) ? folder : resolve(cwd, folder), command)).find(isFile);
+        if (found)
+            return found;
+    }
+    return null;
+}
+/** The characters cmd.exe gives a meaning to. A caret before one makes cmd.exe read it as text. */
+const cmdSpecial = /[()\][%!^"`<>&|;, *?]/g;
+const caret = (text) => text.replace(cmdSpecial, "^$&");
+/**
+ * An argument as one word of a command line that cmd.exe runs, so the program receives exactly
+ * the argument: plain words as they are, and anything else quoted the way Windows programs split
+ * their command line (CommandLineToArgvW: backslashes before a quote doubled, the quote escaped),
+ * then with a caret before each character cmd.exe would act on. That covers quotes, so cmd.exe
+ * never reads the argument as its own quoted text, and `%`, which breaks up `%VAR%`. A batch file
+ * such as an npm shim passes its arguments on in a line cmd.exe reads again, so for one the carets
+ * are added twice (`passes`). The method is https://qntm.org/cmd, as cross-spawn applies it.
+ *
+ * A line break ends the command for cmd.exe whatever surrounds it, so it's refused.
+ */
+export function quoteForCmd(argument, passes = 1) {
+    if (/[\r\n]/.test(argument)) {
+        throw new Error(`An argument with a line break can't be passed to a command through cmd.exe: ${JSON.stringify(argument)}`);
+    }
+    if (/^[\w@+=:,./\\-]+$/.test(argument))
+        return argument;
+    let quoted = '"';
+    let backslashes = 0;
+    for (const character of argument) {
+        if (character === "\\") {
+            backslashes++;
+            continue;
+        }
+        quoted += character === '"' ? "\\".repeat(backslashes * 2 + 1) + '"' : "\\".repeat(backslashes) + character;
+        backslashes = 0;
+    }
+    quoted += "\\".repeat(backslashes * 2) + '"';
+    for (let pass = 0; pass < passes; pass++)
+        quoted = caret(quoted);
+    return quoted;
+}
+/**
+ * The command line for cmd.exe: the command with a caret before each special character (a path
+ * with spaces stays one word), then its arguments, escaped twice for a batch file.
+ */
+export function cmdLine(command, args, batch) {
+    if (/[\r\n]/.test(command))
+        throw new Error(`A command with a line break can't run through cmd.exe: ${JSON.stringify(command)}`);
+    return [caret(command), ...args.map((argument) => quoteForCmd(argument, batch ? 2 : 1))].join(" ");
 }
 /**
- * Starts a command, through the shell on Windows. There it passes one quoted command line, not an
- * argument list: Node warns (DEP0190) when arguments are only concatenated for a shell.
+ * Starts a command. On Windows, with `shell`, it finds the file cmd.exe would run:
+ * - a program (.exe, .com) starts directly, with no shell, so nothing reads its arguments but it;
+ * - a batch file (.cmd, .bat), such as an npm shim, can only start through cmd.exe, and gets one
+ *   command line with every argument escaped for it (Node warns, DEP0190, when arguments are only
+ *   concatenated for a shell);
+ * - anything else goes to cmd.exe too, which runs it or reports that it's missing.
  */
 export function spawnCommand(command, args, options, shell = useShell) {
     if (!shell)
         return spawn(command, args, options);
-    return spawn([command, ...args].map(quoteForCmd).join(" "), { ...options, shell: true });
+    const cwd = options.cwd === undefined ? process.cwd() : typeof options.cwd === "string" ? options.cwd : fileURLToPath(options.cwd);
+    const file = resolveForCmd(command, options.env ?? process.env, cwd);
+    if (file && /\.(exe|com)$/i.test(file))
+        return spawn(file, args, options);
+    return spawn(cmdLine(file ?? command, args, file !== null && /\.(cmd|bat)$/i.test(file)), { ...options, shell: true });
 }
 /** Runs a command with inherited output. Rejects on a non-zero exit. */
 export async function run(command, args, cwd, stdio = "inherit") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.46.0",
+  "version": "0.47.0",
   "description": "Create React apps from Clubedge Starter with a CLI or local MCP server.",
   "type": "module",
   "packageManager": "pnpm@10.9.0",
@@ -24,8 +24,8 @@
   },
   "clubedge": {
     "starterRepository": "Clubedge/clubedge-starter",
-    "starterRef": "v0.30.0",
-    "starterCommit": "4d341955bd13cb170c7385acb745c3d374259897"
+    "starterRef": "v0.31.0",
+    "starterCommit": "e6c47d7b8ec153443ee35abab7fc61d37f55e36a"
   },
   "license": "Apache-2.0",
   "repository": {
@@ -57,7 +57,7 @@
     "release": "node scripts/release.mjs"
   },
   "dependencies": {
-    "@modelcontextprotocol/server": "^2.0.0",
+    "@modelcontextprotocol/server": "^2.4.0",
     "@clack/prompts": "^1.8.1",
     "giget": "^3.3.1",
     "node-diff3": "^3.2.1",
@@ -68,6 +68,6 @@
     "@types/node": "^26.6.5",
     "@types/ssh2": "^1.15.6",
     "typescript": "^5.9.3",
-    "vitest": "^5.0.5"
+    "vitest": "^5.1.0"
   }
 }

package/skills/clubedge-starter/SKILL.md

@@ -16,6 +16,7 @@ Create and manage Clubedge Starter projects through the supported CLI or MCP too
 - If the `clubedge-starter` MCP server is available, call `get_starter_capabilities` first. Treat its response as authoritative for framework/API choices, module options, defaults, and requirements.
 - Before scaffolding through MCP, call `plan_project` with the destination `directory` and requested `stacks` and `modules`. It validates compatibility and previews the files and setup actions without writing to disk. Resolve invalid combinations and any open choices before creating the project. Use `validate_project_config` when only a compatibility check is needed and no destination plan is useful.
 - Use `create_project` to scaffold through MCP. Give `directory` as a relative path beneath the MCP server's working directory. Set `initialize_git` and `install_dependencies` to `true` only when appropriate for the user's request; both default to `false`.
+- With `install_dependencies`, `create_project` answers once `pnpm install` and any toolchain install, such as `uv sync`, have finished, which can take minutes. The server sends progress notifications while they run, so a client that asks for them keeps waiting. If the call times out anyway, the project is already on disk and the server may still be installing: do not create it again. Check the directory, and run `pnpm install` there if the dependencies are missing.
 - If MCP is unavailable, use the CLI. Prefer the installed project-local executable when present; otherwise use `pnpm dlx @clubedge/create-clubedge-app <directory> --yes` and provide the requested options as CLI flags.
 - Use the CLI's `add`, `remove`, or `upgrade` commands for changes to an existing generated project. Do not reproduce those changes by manually copying Starter files.
 

package/template/.dockerignore

@@ -9,3 +9,9 @@ playwright-report
 .output
 .nitro
 .tanstack
+# clubedge:if deploy=cloudflare
+# Wrangler's working files and local secrets (deploy/cloudflare), which change between builds.
+deploy/cloudflare/.wrangler
+deploy/cloudflare/.dev.vars*
+deploy/cloudflare/*.named.jsonc
+# clubedge:end

package/template/.github/workflows/ci.yml

@@ -88,13 +88,6 @@ jobs:
           done
           curl --fail --silent --show-error --output /dev/null http://127.0.0.1:3001/api/health
       # clubedge:end
-      # clubedge:if mobile!=none
-      # package.json's pnpm.auditConfig skips two high advisories in Expo's development CLI
-      # (@expo/cli), which builds and serves the native app but is not part of it: node-forge's,
-      # which has no fixed release, and zod 3's, fixed only in zod 4. pnpm skips them wherever they
-      # appear, so remove them once Expo's CLI no longer needs them. Last checked on 2026-10-26,
-      # with @expo/cli 58.1.15.
-      # clubedge:end
       - run: pnpm audit --audit-level high
 
   # clubedge:if framework!=none
@@ -108,7 +101,8 @@ jobs:
           node-version: 22
           cache: pnpm
       - run: pnpm install --frozen-lockfile
-      - run: pnpm exec playwright install --with-deps chromium
+      # Each engine visitors use (playwright.config.ts): Chrome's, Firefox's, and Safari's WebKit.
+      - run: pnpm exec playwright install --with-deps chromium firefox webkit
       - run: pnpm test:e2e
   # clubedge:end
 

package/template/CONTRIBUTING.md

@@ -21,7 +21,7 @@ pnpm format:check
 pnpm build
 ```
 
-Run `pnpm test:e2e` for changes that affect browser behavior. It requires a locally installed Playwright browser. CI runs the full configured verification workflow for pull requests.
+Run `pnpm test:e2e` for changes that affect browser behavior. It runs in Chromium, Firefox, and WebKit, and requires them installed locally (`pnpm exec playwright install chromium firefox webkit`). CI runs the full configured verification workflow for pull requests.
 
 ## Contribution workflow