@clubedge/create-clubedge-app 0.18.0 → 0.19.1

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.19.1
+
+- `try` now says who can open the preview as Railway does: until the VM is claimed, only the IP address that created it. Another device on mobile data, a VPN, or anyone you send the link to gets Railway's "Access denied" page; claiming makes the URL shareable.
+- Still on Starter `v0.15.0`.
+
+## 0.19.0
+
+- `try` inside a project: `pnpm clubedge try` uploads the project to a free Railway VM and runs it there, to share work in progress without deploying.
+  - It uploads what Git would commit (tracked files, plus untracked ones that are not ignored), and never `.env` files other than examples, `node_modules`, or build output. If Git cannot list a repository's files, nothing is uploaded. `--dry-run` lists the files.
+  - On the VM, the env file is made from `.env.example` as `create` does, then the database (infra `local`), migrations, and the app start as for a new project.
+  - Projects that need Docker or Supabase Auth are refused, with the `pnpm clubedge add` command that switches them.
+- `try` opens the preview in the browser when it is ready, at a terminal; `--no-open` turns that off.
+- Still on Starter `v0.15.0`.
+
 ## 0.18.0
 
 - Add `try` (experimental): `pnpm dlx @clubedge/create-clubedge-app try` creates a new project on a free, temporary [Railway VM](https://railway.com/free-vm) instead of your machine, and prints its preview URL and the link to claim the VM. No Railway account, database, or Docker needed.

package/README.md

@@ -181,16 +181,20 @@ pnpm dlx @clubedge/create-clubedge-app try
 pnpm dlx @clubedge/create-clubedge-app try --framework tanstack-start --auth none
 ```
 
-The VM needs no Railway account and lasts 60 minutes; to keep it, open the claim link the CLI prints within 24 hours after, which moves the VM, its files, and its URL into a Railway account. Keep that link private. Until the VM is claimed, the preview opens only from your network. Railway allows 3 free VMs per network per day.
+The VM needs no Railway account and lasts 60 minutes; to keep it, open the claim link the CLI prints within 24 hours after, which moves the VM, its files, and its URL into a Railway account. Keep that link private. Until the VM is claimed, the preview opens only from the IP address that created it (not from another device on mobile data, or through a VPN); claiming makes the URL shareable. Railway allows 3 free VMs per network per day.
 
-The VM has no Docker, so the project uses `--infra local` (PGlite) and Better Auth unless you choose `--auth none`, with email off; other module flags apply as usual. The CLI asks before creating anything (`--yes` agrees), keeps its own SSH key in your config directory (`~/.config/clubedge`, or `%APPDATA%\clubedge` on Windows) apart from `~/.ssh`, and connects only to Railway's known host key. Railway's [terms](https://railway.com/legal/terms) apply, and Railway can change or pause its free VM.
+The VM has no Docker, so the project uses `--infra local` (PGlite) and Better Auth unless you choose `--auth none`, with email off; other module flags apply as usual.
+
+Inside a project, `pnpm clubedge try` uploads that project instead, to share work in progress without deploying it. It sends what Git would commit (tracked files, plus untracked ones that are not ignored) and never `.env` files other than examples, `node_modules`, or build output; on the VM, the env file is made from `.env.example` as `create` does. The project must use `infra local` or `none`, and not Supabase Auth; `pnpm clubedge add infra local` switches a Docker project. Add `--dry-run` to list the files without uploading anything.
+
+When the app is ready, the CLI opens the preview in your browser; `--no-open` turns that off. The CLI asks before creating anything (`--yes` agrees), keeps its own SSH key in your config directory (`~/.config/clubedge`, or `%APPDATA%\clubedge` on Windows) apart from `~/.ssh`, and connects only to Railway's known host key. Railway's [terms](https://railway.com/legal/terms) apply, and Railway can change or pause its free VM.
 
 ## Version relationship
 
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.18.0
+create-clubedge-app v0.19.1
         |
         v
 Clubedge Starter v0.15.0
@@ -201,7 +205,7 @@ The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.18.0` | `clubedge-starter@v0.15.0` | The CLI's required, tested default |
+| `create-clubedge-app@0.19.1` | `clubedge-starter@v0.15.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`.
 
@@ -293,6 +297,7 @@ Each phase ends with a Starter release and a CLI release pinned to it. The full
 | 0.16.0 | v0.14.0 | Account settings page, browser error reporting and Sentry source maps, auth emails through the jobs queue |
 | 0.17.0 | v0.15.0 | Docs-style dashboard: sidebar with a section switcher and account card, page in a scrolling card, phone drawer |
 | 0.18.0 | v0.15.0 | `try`: a new project on a free, temporary Railway VM, with a preview URL and a claim link (experimental) |
+| 0.19.0 | v0.15.0 | `pnpm clubedge try` uploads an existing project to the VM; the preview opens in the browser |
 | next | | Show the Starter's version of a conflicted file next to yours |
 
 ## Community

package/dist/cli/args.js

@@ -13,6 +13,7 @@ const OPTIONS = {
     "dry-run": { type: "boolean", default: false },
     force: { type: "boolean", default: false },
     services: { type: "boolean", default: true },
+    open: { type: "boolean", default: true },
     help: { type: "boolean", short: "h", default: false },
     version: { type: "boolean", short: "v", default: false },
 };
@@ -111,6 +112,7 @@ export function parseCliArgs(argv) {
         dryRun: values["dry-run"],
         force: values.force,
         services: values.services,
+        open: values.open,
         help: values.help,
         version: values.version,
     };
@@ -148,8 +150,9 @@ function parseCommand(positionals) {
         return { name };
     }
     if (name === "try") {
-        if (module !== undefined)
-            throw new UsageError("Usage: try [--framework <id>] [module flags], for example: try --framework tanstack-start");
+        if (module !== undefined) {
+            throw new UsageError("Usage: try [--framework <id>] [module flags] (a new project), or try inside a project to upload it.");
+        }
         return { name };
     }
     if (name === "upgrade") {

package/dist/cli/ui.js

@@ -94,7 +94,8 @@ Usage:
   pnpm dlx @clubedge/create-clubedge-app try [options]           (experimental)
 
   Inside a project with the clubedge script, use pnpm clubedge add, remove,
-  upgrade, status, or doctor. Without a module or option, add and remove ask for them.
+  upgrade, status, doctor, or try. Without a module or option, add and remove ask
+  for them.
 
   add and remove change modules of an existing project, several at once as one
   change, and upgrade moves it to a newer Starter (this CLI's release unless --ref
@@ -108,9 +109,11 @@ Usage:
 
   try creates a new project on a free, temporary Railway VM (no account, 60 minutes)
   and prints its preview URL and the link to claim the VM. The VM has no Docker, so
-  it uses --infra local (PGlite) and Better Auth, with email off. It asks first, and
-  keeps its own SSH key apart from ~/.ssh. Experimental: Railway can change or pause
-  its free VM.
+  it uses --infra local (PGlite) and Better Auth, with email off. Inside a project,
+  try uploads that project instead (what Git would commit, never .env files or
+  node_modules); it needs infra local or none. It asks first, keeps its own SSH key
+  apart from ~/.ssh, and opens the preview when ready. Experimental: Railway can
+  change or pause its free VM.
 
 Options:
 ${selectionHelp(manifest)}
@@ -120,6 +123,7 @@ ${selectionHelp(manifest)}
   --dry-run               Show what would be created or changed without writing anything
   --force                 add/remove: change a project with uncommitted changes or without Git
   --no-services           doctor: skip pnpm check:services
+  --no-open               try: do not open the preview in the browser
   -y, --yes               Accept defaults and never prompt (default directory: my-app)
   --no-install            Skip dependency installation
   --no-git                Skip Git repository initialization

package/dist/core/railway.js

@@ -77,9 +77,28 @@ export function tryModules(requested) {
     }
     return { ...requested, infra, auth, email: requested.email ?? "none" };
 }
+/**
+ * Why an existing project cannot run on the VM, or null when it can. The VM has no Docker, so the
+ * database must be PGlite (infra local) or none, and Supabase Auth is out.
+ */
+export function projectTryProblem(modules) {
+    const infra = modules.infra ?? "none";
+    if (infra !== "local" && infra !== "none") {
+        return `This project runs its services with infra ${infra}, which needs Docker; the VM has none. Switch with \`pnpm clubedge add infra local\` (PGlite, no Docker), then run try again.`;
+    }
+    if (modules.auth === "supabase") {
+        return "This project signs in with Supabase Auth, which needs Docker or a Supabase project; the VM has neither. Switch with `pnpm clubedge add auth better-auth`, then run try again.";
+    }
+    return null;
+}
+/** A project's package name as a directory name on the VM. */
+export function remoteName(packageName) {
+    const name = packageName.replace(/^@[^/]+\//, "").toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+    return name || "my-app";
+}
 /** A value as one single-quoted shell word. */
 export const shellQuote = (value) => `'${value.replaceAll("'", `'\\''`)}'`;
-/** The create command run on the VM: this CLI's own version, with the chosen selection. */
+/** The create command's flags on the VM: the chosen selection, without prompts. */
 export function tryCreateArgs({ framework, modules, ref }) {
     return [
         ...(framework ? ["--framework", framework] : []),
@@ -93,14 +112,26 @@ export const remoteLog = `${remoteDir}/clubedge-try.log`;
 export const remoteDevLog = `${remoteDir}/clubedge-dev.log`;
 export const remoteScriptPath = `${remoteDir}/clubedge-try.sh`;
 export const remoteProxyPath = `${remoteDir}/clubedge-proxy.mjs`;
+export const remoteArchivePath = `${remoteDir}/clubedge-upload.tgz`;
 /**
- * The script the VM runs. It reports progress on stdout as "@@step <text>", then "@@ready", or
- * "@@fail <text>" followed by the end of the log as "@@log <line>". The servers it starts keep
+ * The script the VM runs. It reports progress on stdout as "@@step <text>", then "@@ready <dir>",
+ * or "@@fail <text>" followed by the end of the log as "@@log <line>". The servers it starts keep
  * running after the SSH session ends.
  */
-export function tryScript(options) {
-    const create = ["pnpm", "dlx", `@clubedge/create-clubedge-app@${options.cliVersion}`, '"$dir"', ...tryCreateArgs(options).map(shellQuote)].join(" ");
-    const betterAuth = options.modules.auth === "better-auth";
+export function tryScript({ source, modules, previewUrl }) {
+    const base = source.kind === "create" ? "my-app" : source.name;
+    const prepare = source.kind === "create"
+        ? `step "Creating the project in ${remoteDir}/$dir"
+${["pnpm", "dlx", `@clubedge/create-clubedge-app@${source.cliVersion}`, '"$dir"', ...tryCreateArgs({ ...source, modules }).map(shellQuote)].join(" ")} >>"$log" 2>&1 || fail "The project could not be created"
+cd "$dir" || fail "The project directory is missing"`
+        : `step "Unpacking the project in ${remoteDir}/$dir"
+mkdir -p "$dir" && tar xzf ${remoteArchivePath} -C "$dir" >>"$log" 2>&1 || fail "The upload could not be unpacked"
+rm -f ${remoteArchivePath}
+cd "$dir" || fail "The project directory is missing"
+step "Installing dependencies"
+pnpm install >>"$log" 2>&1 || fail "pnpm install failed"`;
+    const betterAuth = modules.auth === "better-auth";
+    const localDb = modules.infra === "local";
     return `#!/usr/bin/env bash
 # Written by create-clubedge-app try. Logs: ${remoteLog}, ${remoteDevLog}
 set -uo pipefail
@@ -114,41 +145,56 @@ port="\${PORT:-8080}"
 step "Preparing pnpm"
 command -v pnpm >/dev/null 2>&1 || corepack enable pnpm >>"$log" 2>&1 || npm install -g pnpm@10 >>"$log" 2>&1 || fail "pnpm could not be installed"
 
-# A second run on the same VM replaces the servers of the first, and creates a new directory.
+# A second run on the same VM replaces the servers of the first, and uses a new directory.
 pkill -f clubedge-proxy.mjs >/dev/null 2>&1
 pkill -f "next dev|vite dev|local-db" >/dev/null 2>&1
 
 step "Starting the preview proxy"
-setsid nohup node ${remoteProxyPath} "$port" 3000 ${shellQuote(options.previewUrl)} >>${remoteDir}/clubedge-proxy.log 2>&1 < /dev/null &
+setsid nohup node ${remoteProxyPath} "$port" 3000 ${shellQuote(previewUrl)} >>${remoteDir}/clubedge-proxy.log 2>&1 < /dev/null &
 
-dir=my-app
+base=${shellQuote(base)}
+dir="$base"
 n=2
-while [ -e "$dir" ]; do dir="my-app-$n"; n=$((n + 1)); done
-step "Creating the project in ${remoteDir}/$dir"
-${create} >>"$log" 2>&1 || fail "The project could not be created"
-cd "$dir" || fail "The project directory is missing"
+while [ -e "$dir" ]; do dir="$base-$n"; n=$((n + 1)); done
+${prepare}
+
+# The local env file from the example, as create does (the Starter's env.example and env.target);
+# an uploaded project has none, since env files never leave the user's machine.
+if [ -f .env.example ] && [ -d apps/web ] && [ ! -f apps/web/.env.local ]; then cp .env.example apps/web/.env.local; fi
+for example in apps/*/.env.example; do
+  [ -f "$example" ] || continue
+  target="\${example%.example}.local"
+  [ -f "$target" ] || cp "$example" "$target"
+done
 ${betterAuth
         ? `
-envfile=$(ls apps/*/.env.local 2>/dev/null | head -n 1)
-[ -n "$envfile" ] || fail "The project has no apps/*/.env.local"
 secret=$(node -e 'console.log(require("node:crypto").randomBytes(32).toString("hex"))')
-if grep -q '^BETTER_AUTH_SECRET=' "$envfile"; then
-  sed -i "s/^BETTER_AUTH_SECRET=.*/BETTER_AUTH_SECRET=$secret/" "$envfile"
-else
-  echo "BETTER_AUTH_SECRET=$secret" >> "$envfile"
-fi
+for envfile in apps/*/.env.local; do
+  [ -f "$envfile" ] || continue
+  if grep -q '^BETTER_AUTH_SECRET=' "$envfile"; then
+    sed -i "s/^BETTER_AUTH_SECRET=.*/BETTER_AUTH_SECRET=$secret/" "$envfile"
+  else
+    echo "BETTER_AUTH_SECRET=$secret" >> "$envfile"
+  fi
+done
 `
-        : ""}
+        : ""}${localDb
+        ? `
 step "Starting the local database"
-setsid nohup pnpm infra:up >>${remoteDir}/clubedge-db.log 2>&1 < /dev/null &
-for _ in $(seq 120); do grep -q "Local database ready" ${remoteDir}/clubedge-db.log && break; sleep 1; done
-grep -q "Local database ready" ${remoteDir}/clubedge-db.log || { cat ${remoteDir}/clubedge-db.log >> "$log"; fail "The local database did not start"; }
+db=${remoteDir}/clubedge-db.log
+: > "$db"
+setsid nohup pnpm infra:up >>"$db" 2>&1 < /dev/null &
+for _ in $(seq 120); do grep -q "Local database ready" "$db" && break; sleep 1; done
+grep -q "Local database ready" "$db" || { cat "$db" >> "$log"; fail "The local database did not start"; }
 
 step "Migrating the database"
 pnpm run --if-present db:migrate >>"$log" 2>&1 || fail "The database migration failed"
-
+`
+        : ""}
 step "Starting the app"
+: > ${remoteDevLog}
 setsid nohup pnpm dev >>${remoteDevLog} 2>&1 < /dev/null &
+code=000
 for _ in $(seq 300); do
   code=$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:3000/ || true)
   [ "$code" != "000" ] && break

package/dist/core/upload.js

@@ -0,0 +1,91 @@
+import { execFile } from "node:child_process";
+import { readdir, stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { promisify } from "node:util";
+/*
+ * Which files of a project leave the machine when `try` uploads it: what Git would commit, never
+ * an env file other than an example, and never installed or built output.
+ */
+const skippedDirectories = new Set([
+    "node_modules",
+    ".git",
+    ".next",
+    ".turbo",
+    ".output",
+    ".vinxi",
+    ".tanstack",
+    ".vercel",
+    ".netlify",
+    ".data",
+    "dist",
+    "coverage",
+    "playwright-report",
+    "test-results",
+]);
+/** Whether a project-relative path (forward slashes) may be uploaded. */
+export function isUploadable(path) {
+    const segments = path.split("/");
+    if (segments.some((segment) => skippedDirectories.has(segment)))
+        return false;
+    const name = segments.at(-1) ?? "";
+    // .env, .env.local, .env.production... hold secrets; .env.example only names the variables.
+    if (/^\.env(\.|$)/.test(name) && !name.endsWith(".example"))
+        return false;
+    return name !== ".DS_Store";
+}
+async function walk(root, directory = "") {
+    const entries = await readdir(join(root, directory), { withFileTypes: true });
+    const paths = [];
+    for (const entry of entries) {
+        const path = directory ? `${directory}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            if (!skippedDirectories.has(entry.name))
+                paths.push(...(await walk(root, path)));
+        }
+        else if (entry.isFile()) {
+            paths.push(path);
+        }
+    }
+    return paths;
+}
+/** Whether `root` or a folder above it is a Git repository (a .git directory, or a .git file in a worktree). */
+async function insideGit(root) {
+    for (let current = resolve(root);; current = dirname(current)) {
+        try {
+            await stat(join(current, ".git"));
+            return true;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        if (dirname(current) === current)
+            return false;
+    }
+}
+/**
+ * The project's files to upload. In a Git repository: tracked files plus untracked ones that are
+ * not ignored, so .gitignore decides as it does for a commit. Elsewhere: every file outside the
+ * skipped directories. Either way, isUploadable has the last word.
+ */
+export async function uploadableFiles(root) {
+    let paths;
+    try {
+        // git runs without a shell (it is an executable on every platform), with room for large repositories.
+        const { stdout } = await promisify(execFile)("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], {
+            cwd: root,
+            maxBuffer: 64 * 1024 * 1024,
+        });
+        paths = [...new Set(stdout.split("\0").filter(Boolean))];
+    }
+    catch (error) {
+        // Inside a repository, only Git knows what .gitignore keeps out; walking instead could upload
+        // ignored files. So fall back only where there is no repository at all.
+        if (await insideGit(root)) {
+            const reason = error instanceof Error ? (error.message.split(/\r?\n/)[0] ?? error.message) : String(error);
+            throw new Error(`Could not list the project's files with Git, so nothing was uploaded: ${reason}`);
+        }
+        paths = await walk(root);
+    }
+    return paths.filter(isUploadable).sort();
+}

package/dist/try.js

@@ -6,8 +6,12 @@ import process from "node:process";
 import ssh2 from "ssh2";
 import { UsageError } from "./cli/args.js";
 import { bold, dim } from "./cli/ui.js";
-import { hostKeyFingerprint, parseRailwayStatus, proxySource, railwayFreeVmUrl, railwayHost, railwayKeyPath, railwayTermsUrl, remoteDevLog, remoteLog, remoteProxyPath, remoteScriptPath, shellQuote, trustedHostKeys, tryCreateArgs, tryModules, tryScript, } from "./core/railway.js";
+import { hostKeyFingerprint, parseRailwayStatus, projectTryProblem, proxySource, railwayFreeVmUrl, railwayHost, railwayKeyPath, railwayTermsUrl, remoteArchivePath, remoteDevLog, remoteLog, remoteName, remoteProxyPath, remoteScriptPath, shellQuote, trustedHostKeys, tryCreateArgs, tryModules, tryScript, } from "./core/railway.js";
+import { ProjectError, readProject } from "./core/project.js";
+import { uploadableFiles } from "./core/upload.js";
 import { cliVersion } from "./package-info.js";
+import { openUrl } from "./utils/open.js";
+import { createTarGz } from "./utils/tar.js";
 const { Client, utils } = ssh2;
 /** The CLI's own key: created on first use, then reused so later runs reach the same VM. */
 async function loadOrCreateKey(path) {
@@ -110,12 +114,55 @@ const fit = (text) => {
 function minutesLeft(until) {
     return Math.max(0, Math.round((until.getTime() - Date.now()) / 60_000));
 }
-async function agree(args, keyPath) {
+const megabytes = (bytes) => `${(bytes / 1_048_576).toFixed(1)} MB`;
+/** The project this command runs in, or null outside one. A project too old to read is an error. */
+async function currentProject() {
+    try {
+        return await readProject(process.cwd());
+    }
+    catch (error) {
+        if (error instanceof ProjectError && /No Clubedge project found/.test(error.message))
+            return null;
+        throw error;
+    }
+}
+async function plan(args) {
+    const project = await currentProject();
+    if (!project) {
+        const modules = tryModules(args.modules);
+        const flags = tryCreateArgs({ framework: args.framework, modules, ref: args.ref }).join(" ");
+        return { kind: "create", modules, summary: `Create a new project on the VM: create-clubedge-app@${cliVersion} my-app ${flags}` };
+    }
+    if (args.framework !== undefined || Object.keys(args.modules).length || args.ref !== undefined) {
+        throw new UsageError("--framework, module flags, and --ref choose a new project. Inside a project, try uploads the project as it is; run try outside it to create a new one.");
+    }
+    const problem = projectTryProblem(project.modules);
+    if (problem)
+        throw new UsageError(problem);
+    const paths = await uploadableFiles(project.root);
+    if (!paths.includes("package.json"))
+        throw new UsageError(`Nothing to upload from ${project.root}.`);
+    return {
+        kind: "upload",
+        modules: project.modules,
+        project,
+        paths,
+        summary: `Upload ${project.identity.packageName} (${paths.length} files from ${project.root}): what Git would commit, without .env files or node_modules`,
+    };
+}
+async function agree(args, keyPath, what) {
     note([
-        "This creates a free, temporary Linux VM on Railway and runs a new project there.",
+        what.kind === "create"
+            ? "This creates a free, temporary Linux VM on Railway and runs a new project there."
+            : "This creates a free, temporary Linux VM on Railway, uploads this project, and runs it there.",
         "",
+        ...(what.kind === "upload"
+            ? [
+                `• Uploads ${what.paths.length} files: what Git would commit. .env files (other than examples) and node_modules stay here; the VM makes its env files from .env.example.`,
+            ]
+            : []),
         `• No Railway account is needed. You get 60 minutes, then 24 hours to claim the VM to keep it.`,
-        `• The preview opens only from your network until you claim the VM.`,
+        `• Until you claim the VM, only you can open the preview: from the IP address that created it (this connection). Your phone on mobile data, a VPN, or anyone else get Access denied.`,
         `• Railway allows 3 free VMs per network per day.`,
         `• The CLI uses its own SSH key, ${keyPath}; your ~/.ssh is not used.`,
         `• Railway's terms apply: ${railwayTermsUrl}`,
@@ -131,19 +178,21 @@ async function agree(args, keyPath) {
     return !isCancel(answer) && answer;
 }
 export async function tryOnRailway(args) {
-    const modules = tryModules(args.modules);
+    const what = await plan(args);
     const keyPath = railwayKeyPath();
-    const createArgs = tryCreateArgs({ framework: args.framework, modules, ref: args.ref });
     if (args.dryRun) {
         log.message([
             `• Connect to ${railwayHost} with the key in ${keyPath}`,
-            `• Create the project: create-clubedge-app@${cliVersion} my-app ${createArgs.join(" ")}`,
-            "• Start the local database (PGlite), migrate, and start the app behind the preview URL",
+            `• ${what.summary}`,
+            what.modules.infra === "local"
+                ? "• Start the local database (PGlite), migrate, and start the app behind the preview URL"
+                : "• Start the app behind the preview URL",
+            ...(what.kind === "upload" ? ["", dim(what.paths.join("\n"))] : []),
         ].join("\n"));
         outro("Dry run: no VM was created. Run again without --dry-run to try it.");
         return;
     }
-    if (!(await agree(args, keyPath))) {
+    if (!(await agree(args, keyPath, what))) {
         cancel("No VM was created.");
         return;
     }
@@ -161,12 +210,23 @@ export async function tryOnRailway(args) {
             throw new Error(`${railwayHost} did not describe the VM. Railway may have changed its free VM; see ${railwayFreeVmUrl}.`);
         progress.stop(`VM ready, ${minutesLeft(vm.expiresAt)} minutes to try it`);
         spinning = "setup";
-        progress.start("Preparing the VM");
+        let source;
+        if (what.kind === "upload") {
+            progress.start(`Uploading ${what.paths.length} files`);
+            const { archive, bytes } = await createTarGz(what.project.root, what.paths);
+            await upload(connection, remoteArchivePath, archive);
+            progress.message(`Uploaded ${megabytes(bytes)} (${megabytes(archive.length)} compressed)`);
+            source = { kind: "upload", name: remoteName(what.project.identity.packageName) };
+        }
+        else {
+            progress.start("Preparing the VM");
+            source = { kind: "create", cliVersion, framework: args.framework, ref: args.ref };
+        }
         await upload(connection, remoteProxyPath, proxySource);
-        await upload(connection, remoteScriptPath, tryScript({ cliVersion, framework: args.framework, modules, ref: args.ref, previewUrl: vm.previewUrl }));
+        await upload(connection, remoteScriptPath, tryScript({ source, modules: what.modules, previewUrl: vm.previewUrl }));
         const tail = [];
         let failure = "";
-        let directory = "my-app";
+        let directory = "";
         const started = Date.now();
         const { code } = await exec(connection, `bash ${remoteScriptPath}`, {
             onLine: (line) => {
@@ -177,7 +237,7 @@ export async function tryOnRailway(args) {
                 else if (line.startsWith("@@fail "))
                     failure = line.slice(7);
                 else if (line.startsWith("@@ready"))
-                    directory = line.slice(8).trim() || directory;
+                    directory = line.slice(8).trim();
             },
         });
         if (code !== 0 || failure) {
@@ -195,8 +255,11 @@ export async function tryOnRailway(args) {
             `${bold("Claim")}    ${vm.claimUrl}`,
         ].join("\n"), "Your app on Railway");
         log.warn("Keep the claim link private: whoever opens it takes over the VM, its files, and its URL.");
+        // Only for a person at a terminal: scripts and CI get the URL above, and nothing opens.
+        if (args.open && process.stdout.isTTY && (await openUrl(vm.previewUrl)))
+            log.info("Opened the preview in your browser.");
         outro([
-            "The preview opens only from your network until you claim the VM. Claiming moves it to your Railway account.",
+            "Until you claim the VM, the preview opens only from the IP address that created it. Claiming moves it to your Railway account and makes the URL shareable.",
             "",
             `${dim("Shell")}  ssh -i "${keyPath}" ${railwayHost}`,
             `${dim("Logs")}   ssh -i "${keyPath}" ${railwayHost} tail -f ${remoteDevLog}`,

package/dist/utils/open.js

@@ -0,0 +1,27 @@
+import { spawn } from "node:child_process";
+import process from "node:process";
+/** The command that opens a URL in the default browser on this platform. */
+export function openCommand(url, platform = process.platform) {
+    if (platform === "win32")
+        return ["rundll32", ["url.dll,FileProtocolHandler", url]];
+    if (platform === "darwin")
+        return ["open", [url]];
+    return ["xdg-open", [url]];
+}
+/** 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);
+    return await new Promise((resolve) => {
+        try {
+            const child = spawn(command, args, { detached: true, stdio: "ignore" });
+            child.once("error", () => resolve(false));
+            child.once("spawn", () => {
+                child.unref();
+                resolve(true);
+            });
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}

package/dist/utils/tar.js

@@ -0,0 +1,67 @@
+import { lstat, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { gzipSync } from "node:zlib";
+/*
+ * A minimal ustar writer: regular files only, as a gzipped archive in memory. Enough to send a
+ * project's source to a VM in one stream, without a tar dependency or a system tar on Windows.
+ */
+const block = 512;
+function octal(value, length) {
+    return value.toString(8).padStart(length - 1, "0") + "\0";
+}
+/** ustar keeps the path in name (100 bytes) and prefix (155 bytes), split at a slash. */
+function splitPath(path) {
+    if (Buffer.byteLength(path) <= 100)
+        return { name: path, prefix: "" };
+    for (let i = path.indexOf("/"); i !== -1; i = path.indexOf("/", i + 1)) {
+        const prefix = path.slice(0, i);
+        const name = path.slice(i + 1);
+        if (Buffer.byteLength(prefix) <= 155 && Buffer.byteLength(name) <= 100)
+            return { name, prefix };
+    }
+    throw new Error(`The path ${path} is too long to upload.`);
+}
+function header(path, size, mode, mtime) {
+    const buffer = Buffer.alloc(block);
+    const { name, prefix } = splitPath(path);
+    buffer.write(name, 0, 100, "utf8");
+    buffer.write(octal(mode, 8), 100, 8, "ascii");
+    buffer.write(octal(0, 8), 108, 8, "ascii");
+    buffer.write(octal(0, 8), 116, 8, "ascii");
+    buffer.write(octal(size, 12), 124, 12, "ascii");
+    buffer.write(octal(mtime, 12), 136, 12, "ascii");
+    buffer.write("        ", 148, 8, "ascii");
+    buffer.write("0", 156, 1, "ascii");
+    buffer.write("ustar\0", 257, 6, "ascii");
+    buffer.write("00", 263, 2, "ascii");
+    buffer.write(prefix, 345, 155, "utf8");
+    let sum = 0;
+    for (const byte of buffer)
+        sum += byte;
+    buffer.write(`${sum.toString(8).padStart(6, "0")}\0 `, 148, 8, "ascii");
+    return buffer;
+}
+/**
+ * Packs the files at `paths` (relative, with forward slashes) under `root` into a .tar.gz.
+ * Missing files and anything that is not a regular file are skipped.
+ */
+export async function createTarGz(root, paths) {
+    const parts = [];
+    let files = 0;
+    let bytes = 0;
+    for (const path of paths) {
+        const stats = await lstat(join(root, path)).catch(() => null);
+        if (!stats?.isFile())
+            continue;
+        const content = await readFile(join(root, path));
+        const executable = (stats.mode & 0o111) !== 0;
+        parts.push(header(path, content.length, executable ? 0o755 : 0o644, Math.floor(stats.mtimeMs / 1000)), content);
+        const padding = (block - (content.length % block)) % block;
+        if (padding)
+            parts.push(Buffer.alloc(padding));
+        files += 1;
+        bytes += content.length;
+    }
+    parts.push(Buffer.alloc(block * 2));
+    return { archive: gzipSync(Buffer.concat(parts)), files, bytes };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.18.0",
+  "version": "0.19.1",
   "description": "Create a Next.js or TanStack Start application from the Clubedge Starter reference implementation.",
   "type": "module",
   "packageManager": "pnpm@10.9.0",