@clubedge/create-clubedge-app 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 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.
+  - The VM has no Docker, so the project uses `--infra local` (PGlite) and Better Auth, with email off; `--framework` and other module flags apply as usual. `--infra` other than `local` and `--auth supabase` are rejected.
+  - It asks before creating anything (`--yes` agrees), keeps its own SSH key in the CLI's config directory apart from `~/.ssh`, and connects only to Railway's known host key (`CLUBEDGE_RAILWAY_HOST_KEY` adds one if Railway rotates it).
+  - The VM lasts 60 minutes and can be claimed for 24 hours after; until then, the preview opens only from your network. Railway allows 3 free VMs per network per day.
+- Still on Starter `v0.15.0`.
+
 ## 0.17.0
 
 - Default to Starter `v0.15.0`, whose dashboard has the docs' layout and colors in both frameworks: a collapsible sidebar with a section switcher, the dashboard's sections, resources, and an account card with Settings and Sign out; the page in a rounded card that scrolls on its own; a top bar with Home, GitHub, and a light and dark switch; and a drawer on phones.

package/README.md

@@ -172,12 +172,29 @@ pnpm clubedge doctor    # Node.js, pnpm, dependencies, lockfile, env file, and p
 
 `status` ends with the command to run next, such as `pnpm clubedge upgrade` when a newer Starter release is available; it asks npm for the newest CLI and still works offline. `doctor` checks that Node.js and pnpm meet the project's versions, that dependencies are installed, that `pnpm-lock.yaml` matches every `package.json`, and that `apps/web/.env.local` has every variable in `.env.example`, then runs `pnpm check:services` (skip it with `--no-services`). It exits with an error when a check fails, so it also works in CI.
 
+## Try it on a Railway VM (experimental)
+
+No Node.js setup, database, or Docker to spare? `try` creates the project on a free, temporary Linux VM from [Railway](https://railway.com/free-vm) instead of your machine, and prints a preview URL:
+
+```sh
+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 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.17.0
+create-clubedge-app v0.19.0
         |
         v
 Clubedge Starter v0.15.0
@@ -188,7 +205,7 @@ The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.17.0` | `clubedge-starter@v0.15.0` | The CLI's required, tested default |
+| `create-clubedge-app@0.19.0` | `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`.
 
@@ -279,6 +296,8 @@ Each phase ends with a Starter release and a CLI release pinned to it. The full
 | 0.15.0 | v0.13.1 | `status` and `doctor`, several modules in one change, conflict and upgrade summaries, macOS CI |
 | 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 },
 };
@@ -75,15 +76,20 @@ export function parseCliArgs(argv) {
     }
     const { values, positionals } = parsed;
     const command = parseCommand(positionals);
+    // try creates a project too, on a VM, so it takes the same selection flags as create.
+    const creates = command.name === "create" || command.name === "try";
     if (command.name === "create" && positionals.length > 1) {
         throw new UsageError("Only one project directory can be provided.");
     }
-    if (command.name !== "create" && (values.framework !== undefined || Object.keys(modules).length)) {
+    if (!creates && (values.framework !== undefined || Object.keys(modules).length)) {
         throw new UsageError("--framework and module flags only apply when creating a project; use add or remove to change modules.");
     }
-    if (command.name !== "create" && command.name !== "upgrade" && values.ref !== undefined) {
+    if (!creates && command.name !== "upgrade" && values.ref !== undefined) {
         throw new UsageError("--ref only applies when creating or upgrading a project.");
     }
+    if (command.name === "try" && values["template-dir"] !== undefined) {
+        throw new UsageError("--template-dir does not apply to try: the VM downloads the Starter itself.");
+    }
     if (values.framework !== undefined && !values.framework.trim()) {
         throw new UsageError("--framework requires a framework id, such as next or tanstack-start.");
     }
@@ -106,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,
     };
@@ -116,9 +123,9 @@ function assertDistinct(modules) {
         throw new UsageError(`The module "${repeated}" is named more than once.`);
 }
 /**
- * `add <module> <option>...`, `remove <module>...`, and `upgrade` change an existing project, and `status`
- * and `doctor` inspect one; anything else is the directory of a new project. Create a project
- * literally named "add" with `./add`.
+ * `add <module> <option>...`, `remove <module>...`, and `upgrade` change an existing project, `status`
+ * and `doctor` inspect one, and `try` creates one on a Railway VM; anything else is the directory
+ * of a new project. Create a project literally named "add" with `./add`.
  */
 function parseCommand(positionals) {
     const [name, ...rest] = positionals;
@@ -142,6 +149,12 @@ function parseCommand(positionals) {
             throw new UsageError(`Usage: ${name}, run inside a project.`);
         return { name };
     }
+    if (name === "try") {
+        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") {
         if (module !== undefined)
             throw new UsageError("Usage: upgrade [--ref <tag>], for example: upgrade --ref v0.8.0");

package/dist/cli/ui.js

@@ -91,9 +91,11 @@ Usage:
   pnpm dlx @clubedge/create-clubedge-app upgrade [--ref <tag>]   (inside a project)
   pnpm dlx @clubedge/create-clubedge-app status                  (inside a project)
   pnpm dlx @clubedge/create-clubedge-app doctor                  (inside a project)
+  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
@@ -105,6 +107,14 @@ Usage:
   newer Starter is available. doctor checks Node.js, pnpm, the dependencies, the
   lockfile, and the env file, then runs pnpm check:services; it changes nothing.
 
+  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. 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)}
   --ref <ref>             Download this Starter tag, branch, or commit from GitHub instead
@@ -113,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
@@ -132,6 +143,7 @@ Examples:
   pnpm dlx @clubedge/create-clubedge-app@latest upgrade
   pnpm clubedge status
   pnpm clubedge doctor --no-services
+  pnpm dlx @clubedge/create-clubedge-app try --framework tanstack-start
 
 Learn more:
   CLI      ${cliUrl}

package/dist/core/railway.js

@@ -0,0 +1,268 @@
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import process from "node:process";
+import { UsageError } from "../cli/args.js";
+/*
+ * Railway's free VM (https://railway.com/free-vm): `ssh railway.new` gives a temporary Linux box
+ * with no account. Everything this CLI relies on about it is in this file, so a change on
+ * Railway's side is a change here.
+ */
+export const railwayHost = "railway.new";
+export const railwayTermsUrl = "https://railway.com/legal/terms";
+export const railwayFreeVmUrl = "https://railway.com/free-vm";
+/**
+ * The host keys railway.new presents, as OpenSSH SHA256 fingerprints. Connecting to anything
+ * else fails. CLUBEDGE_RAILWAY_HOST_KEY adds one (comma-separated), for when Railway rotates its
+ * key before a CLI release catches up.
+ */
+const pinnedHostKeys = ["SHA256:+S1xg92FrnHz6pY3bpkmh1OGtWQGNANXilPzlxA7B1g"];
+export function trustedHostKeys(env = process.env) {
+    const extra = (env.CLUBEDGE_RAILWAY_HOST_KEY ?? "")
+        .split(",")
+        .map((value) => value.trim())
+        .filter(Boolean);
+    return [...pinnedHostKeys, ...extra];
+}
+/** The OpenSSH fingerprint of a raw host key: "SHA256:" and unpadded base64, as ssh prints it. */
+export function hostKeyFingerprint(key) {
+    return `SHA256:${createHash("sha256").update(key).digest("base64").replace(/=+$/, "")}`;
+}
+/**
+ * Finds Railway's JSON status line in a command's stderr. Returns null when there is none, and
+ * throws when there is one without the fields this CLI needs.
+ */
+export function parseRailwayStatus(stderr) {
+    for (const line of stderr.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("{"))
+            continue;
+        let value;
+        try {
+            value = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (typeof value.status !== "string")
+            continue;
+        const previewUrl = value.preview_url;
+        const claimUrl = value.human_claim_url;
+        const expiresAt = new Date(String(value.build_expires_at));
+        if (typeof previewUrl !== "string" || !/^https:\/\//.test(previewUrl) || typeof claimUrl !== "string" || Number.isNaN(expiresAt.getTime())) {
+            throw new Error(`Railway answered, but not as this CLI expects (status "${value.status}"). Railway may have changed its free VM; update the CLI, or see ${railwayFreeVmUrl}.`);
+        }
+        return { status: value.status, state: String(value.state ?? ""), previewUrl: previewUrl.replace(/\/+$/, ""), claimUrl, expiresAt };
+    }
+    return null;
+}
+/** Where the CLI keeps its own SSH key for Railway, apart from the user's ~/.ssh. */
+export function railwayKeyPath(env = process.env, platform = process.platform) {
+    const configHome = env.XDG_CONFIG_HOME || (platform === "win32" && env.APPDATA ? env.APPDATA : join(homedir(), ".config"));
+    return join(configHome, "clubedge", "railway_ed25519");
+}
+/**
+ * The modules for a project on the VM. It has no Docker, so the database is PGlite (--infra
+ * local) and sign-in is Better Auth; email is off, since nothing there receives it. Flags the
+ * user passed win, unless the VM cannot run them.
+ */
+export function tryModules(requested) {
+    const infra = requested.infra ?? "local";
+    if (infra !== "local") {
+        throw new UsageError(`try runs on a VM without Docker, so it needs --infra local (not --infra ${infra}).`);
+    }
+    const auth = requested.auth ?? "better-auth";
+    if (auth === "supabase") {
+        throw new UsageError("try cannot run Supabase Auth, which needs Docker or a Supabase project. Use --auth better-auth or --auth none.");
+    }
+    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's flags on the VM: the chosen selection, without prompts. */
+export function tryCreateArgs({ framework, modules, ref }) {
+    return [
+        ...(framework ? ["--framework", framework] : []),
+        ...Object.entries(modules).flatMap(([module, option]) => [`--${module}`, option]),
+        ...(ref ? ["--ref", ref] : []),
+        "--yes",
+    ];
+}
+export const remoteDir = "/app";
+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 <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({ 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
+cd ${remoteDir}
+log=${remoteLog}
+: > "$log"
+step() { echo "@@step $*"; echo "== $*" >> "$log"; }
+fail() { echo "@@fail $*"; tail -n 40 "$log" | sed 's/^/@@log /'; exit 1; }
+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 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(previewUrl)} >>${remoteDir}/clubedge-proxy.log 2>&1 < /dev/null &
+
+base=${shellQuote(base)}
+dir="$base"
+n=2
+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
+        ? `
+secret=$(node -e 'console.log(require("node:crypto").randomBytes(32).toString("hex"))')
+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"
+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
+  sleep 1
+done
+[ "$code" != "000" ] || { tail -n 40 ${remoteDevLog} >> "$log"; fail "The app did not start"; }
+echo "@@ready $dir"
+`;
+}
+/**
+ * A small reverse proxy for the VM: Railway's preview URL reaches it on $PORT, and it forwards to
+ * the dev server on localhost. The Starter's dev servers only serve their scripts to localhost
+ * (Next.js allowedDevOrigins, Vite's host check), and Next.js compares Origin with the forwarded
+ * host for form posts, so requests are made to look local, and redirects to localhost are pointed
+ * back at the preview URL. Until the app answers, it shows a page that reloads itself.
+ */
+export const proxySource = `import http from "node:http";
+import net from "node:net";
+
+const [port = "8080", upstreamPort = "3000", publicOrigin = ""] = process.argv.slice(2);
+const local = "http://localhost:" + upstreamPort;
+
+function toLocal(headers) {
+  const result = { ...headers, host: "localhost:" + upstreamPort };
+  delete result["x-forwarded-host"];
+  delete result.forwarded;
+  if (result.origin) result.origin = local;
+  if (result.referer && publicOrigin) result.referer = result.referer.replace(publicOrigin, local);
+  return result;
+}
+
+const starting = '<!doctype html><meta charset="utf-8"><meta http-equiv="refresh" content="5"><title>Starting</title>' +
+  '<body style="font:16px system-ui;display:grid;place-items:center;height:90vh;color:#444">' +
+  "<p>Your Clubedge app is starting. This page reloads by itself.</p>";
+
+const server = http.createServer((req, res) => {
+  const upstream = http.request(
+    { host: "127.0.0.1", port: Number(upstreamPort), method: req.method, path: req.url, headers: toLocal(req.headers) },
+    (answer) => {
+      const headers = { ...answer.headers };
+      if (headers.location && publicOrigin) headers.location = headers.location.replace(local, publicOrigin);
+      res.writeHead(answer.statusCode ?? 502, headers);
+      answer.pipe(res);
+    },
+  );
+  upstream.on("error", () => {
+    if (res.headersSent) return res.destroy();
+    res.writeHead(503, { "content-type": "text/html; charset=utf-8", "retry-after": "5" });
+    res.end(starting);
+  });
+  req.pipe(upstream);
+});
+
+// Hot reload: pass WebSocket upgrades through with the same local headers.
+server.on("upgrade", (req, socket, head) => {
+  const upstream = net.connect(Number(upstreamPort), "127.0.0.1", () => {
+    const lines = [req.method + " " + req.url + " HTTP/1.1"];
+    for (const [name, value] of Object.entries(toLocal(req.headers))) {
+      for (const item of [].concat(value)) lines.push(name + ": " + item);
+    }
+    upstream.write(lines.join("\\r\\n") + "\\r\\n\\r\\n");
+    if (head && head.length) upstream.write(head);
+    upstream.pipe(socket);
+    socket.pipe(upstream);
+  });
+  upstream.on("error", () => socket.destroy());
+  socket.on("error", () => upstream.destroy());
+});
+
+server.listen(Number(port), "0.0.0.0");
+`;

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/index.js

@@ -11,6 +11,7 @@ import { readBundledTemplate, resolveTemplateSource } from "./core/source.js";
 import { cliUrl, cliVersion, siteUrl, starterPin } from "./package-info.js";
 import { runDoctor, showStatus } from "./inspect.js";
 import { changeProject } from "./modify.js";
+import { tryOnRailway } from "./try.js";
 import { initializeGit } from "./steps/git.js";
 import { detectLauncher, installDependencies, resolvePnpm } from "./steps/install.js";
 import { displayNameFromPackageName, packageNameFromDirectory } from "./utils/names.js";
@@ -234,6 +235,10 @@ export async function main(argv = process.argv.slice(2)) {
             intro("Check this project's setup");
             await runDoctor(args);
         }
+        else if (args.command.name === "try") {
+            intro("Try a project on a free Railway VM");
+            await tryOnRailway(args);
+        }
         else {
             const intros = {
                 add: "Add a module to this project",

package/dist/try.js

@@ -0,0 +1,276 @@
+import { cancel, confirm, isCancel, log, note, outro, spinner } from "@clack/prompts";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { userInfo } from "node:os";
+import { dirname } from "node:path";
+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, 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) {
+    try {
+        return { privateKey: await readFile(path, "utf8"), created: false };
+    }
+    catch {
+        const pair = utils.generateKeyPairSync("ed25519", { comment: "create-clubedge-app try" });
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, pair.private, { mode: 0o600 });
+        await chmod(path, 0o600).catch(() => { });
+        await writeFile(`${path}.pub`, `${pair.public}\n`);
+        return { privateKey: pair.private, created: true };
+    }
+}
+/** Opens the SSH connection, accepting only Railway's pinned host key. */
+async function connect(privateKey) {
+    const trusted = trustedHostKeys();
+    let seen = "";
+    return await new Promise((resolve, reject) => {
+        const connection = new Client();
+        connection
+            .once("ready", () => resolve(connection))
+            .once("error", (error) => {
+            if (seen && !trusted.includes(seen)) {
+                reject(new Error(`${railwayHost} presented an unknown host key (${seen}), so the CLI did not connect. ` +
+                    `If Railway announced a new key, set CLUBEDGE_RAILWAY_HOST_KEY=${seen} and run again.`));
+            }
+            else if (/authentication/i.test(error.message)) {
+                reject(new Error(`Railway refused the connection. The free VM may be paused or at its daily limit; see ${railwayFreeVmUrl}.`));
+            }
+            else {
+                reject(new Error(`Could not reach ${railwayHost}: ${error.message}`));
+            }
+        })
+            .connect({
+            host: railwayHost,
+            port: 22,
+            username: userInfo().username || "clubedge",
+            privateKey,
+            readyTimeout: 30_000,
+            keepaliveInterval: 15_000,
+            hostVerifier: (key) => {
+                seen = hostKeyFingerprint(key);
+                return trusted.includes(seen);
+            },
+        });
+    });
+}
+/**
+ * Runs a command on the VM. Railway's status line on stderr is taken out and parsed; stdout lines
+ * go to onLine as they arrive.
+ */
+async function exec(connection, command, { input, onLine } = {}) {
+    return await new Promise((resolve, reject) => {
+        connection.exec(command, (error, stream) => {
+            if (error)
+                return reject(error);
+            let stdout = "";
+            let stderr = "";
+            let pending = "";
+            stream.on("data", (chunk) => {
+                const text = chunk.toString();
+                stdout += text;
+                pending += text;
+                const lines = pending.split("\n");
+                pending = lines.pop() ?? "";
+                for (const line of lines)
+                    onLine?.(line.replace(/\r$/, ""));
+            });
+            stream.stderr.on("data", (chunk) => (stderr += chunk.toString()));
+            stream.once("close", (code) => {
+                if (pending)
+                    onLine?.(pending);
+                try {
+                    resolve({ code: code ?? 1, stdout, vm: parseRailwayStatus(stderr) });
+                }
+                catch (parseError) {
+                    reject(parseError);
+                }
+            });
+            if (input !== undefined)
+                stream.end(input);
+            else
+                stream.end();
+        });
+    });
+}
+/** Writes a file on the VM through the command's stdin. */
+async function upload(connection, path, content) {
+    const { code } = await exec(connection, `cat > ${shellQuote(path)}`, { input: content });
+    if (code !== 0)
+        throw new Error(`Could not write ${path} on the VM.`);
+}
+// A spinner line wider than the terminal wraps, and each frame then prints a new line.
+const fit = (text) => {
+    const width = (process.stdout.columns ?? 80) - 6;
+    return text.length > width ? `${text.slice(0, width - 1)}…` : text;
+};
+function minutesLeft(until) {
+    return Math.max(0, Math.round((until.getTime() - Date.now()) / 60_000));
+}
+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([
+        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.`,
+        `• 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}`,
+        "",
+        dim(`Experimental: Railway can change or pause its free VM (${railwayFreeVmUrl}).`),
+    ].join("\n"), "Try it on Railway");
+    if (args.yes)
+        return true;
+    if (!process.stdin.isTTY) {
+        throw new UsageError("try creates a VM on Railway. Run it in a terminal to confirm, or pass --yes to agree.");
+    }
+    const answer = await confirm({ message: "Create the VM?", initialValue: true });
+    return !isCancel(answer) && answer;
+}
+export async function tryOnRailway(args) {
+    const what = await plan(args);
+    const keyPath = railwayKeyPath();
+    if (args.dryRun) {
+        log.message([
+            `• Connect to ${railwayHost} with the key in ${keyPath}`,
+            `• ${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, what))) {
+        cancel("No VM was created.");
+        return;
+    }
+    const progress = spinner();
+    progress.start(`Connecting to ${railwayHost}`);
+    let spinning = "connect";
+    let connection;
+    try {
+        const key = await loadOrCreateKey(keyPath);
+        if (key.created)
+            log.info(`Created an SSH key for Railway in ${keyPath}`);
+        connection = await connect(key.privateKey);
+        const { vm } = await exec(connection, "true");
+        if (!vm)
+            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";
+        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({ source, modules: what.modules, previewUrl: vm.previewUrl }));
+        const tail = [];
+        let failure = "";
+        let directory = "";
+        const started = Date.now();
+        const { code } = await exec(connection, `bash ${remoteScriptPath}`, {
+            onLine: (line) => {
+                if (line.startsWith("@@step "))
+                    progress.message(fit(`${line.slice(7)} (${Math.round((Date.now() - started) / 1000)}s)`));
+                else if (line.startsWith("@@log "))
+                    tail.push(line.slice(6));
+                else if (line.startsWith("@@fail "))
+                    failure = line.slice(7);
+                else if (line.startsWith("@@ready"))
+                    directory = line.slice(8).trim();
+            },
+        });
+        if (code !== 0 || failure) {
+            spinning = null;
+            progress.stop(failure || "Setup on the VM failed");
+            if (tail.length)
+                log.message(dim(tail.join("\n")));
+            throw new Error(`Setup on the VM failed. Its log is ${remoteLog}; read it with: ssh -i "${keyPath}" ${railwayHost} cat ${remoteLog}`);
+        }
+        spinning = null;
+        progress.stop(`The app is running in /app/${directory}`);
+        note([
+            `${bold("Preview")}  ${vm.previewUrl}`,
+            `${bold("Time")}     ${minutesLeft(vm.expiresAt)} minutes left (until ${vm.expiresAt.toLocaleTimeString()})`,
+            `${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.",
+            "",
+            `${dim("Shell")}  ssh -i "${keyPath}" ${railwayHost}`,
+            `${dim("Logs")}   ssh -i "${keyPath}" ${railwayHost} tail -f ${remoteDevLog}`,
+        ].join("\n"));
+    }
+    catch (error) {
+        if (spinning)
+            progress.stop(spinning === "connect" ? "Could not start a VM on Railway" : "Setup on the VM failed");
+        throw error;
+    }
+    finally {
+        connection?.end();
+    }
+}

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.17.0",
+  "version": "0.19.0",
   "description": "Create a Next.js or TanStack Start application from the Clubedge Starter reference implementation.",
   "type": "module",
   "packageManager": "pnpm@10.9.0",
@@ -53,10 +53,12 @@
   "dependencies": {
     "@clack/prompts": "^1.8.1",
     "giget": "^2.0.0",
-    "node-diff3": "^3.2.1"
+    "node-diff3": "^3.2.1",
+    "ssh2": "^1.17.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.5",
+    "@types/ssh2": "^1.15.6",
     "typescript": "^5.9.3",
     "vitest": "^5.0.3"
   }