create-rivet 0.1.0-alpha.0 → 0.1.0-alpha.2

package/README.md

@@ -1,6 +1,6 @@
 # create-rivet
 
-Create a [Rivet](https://github.com/rivetjs/rivet) app.
+Create a [Rivet](https://github.com/N1XUS/rivetjs) app.
 
 ```sh
 npm create rivet@latest my-app
@@ -8,7 +8,7 @@ cd my-app
 npm run dev
 ```
 
-It asks for a project name, a template, whether to install dependencies and whether to create a git repository. Other package managers: `pnpm create rivet`, `yarn create rivet`, `bun create rivet`.
+On a terminal it asks for any missing project folder and template, a deploy target, and whether to install dependencies and create a git repository. With `--yes` or non-interactive input, defaults are `rivet-app`, `static`, no deploy adapter, install on and git on. Other package managers: `pnpm create rivet`, `yarn create rivet`, `bun create rivet`.
 
 ## Templates
 
@@ -34,13 +34,20 @@ npm create rivet@latest my-app -- --template server --yes --no-git
 | `-n`, `--name <name>` | `package.json` name (default: the folder name) |
 | `-y`, `--yes` | ask nothing, take the defaults |
 | `--no-install` | skip installing dependencies |
+| `--rivet-version <spec>` | override the `@rivetjs/*` dependency spec (default: this release) |
+| `-v`, `--version` | print the create-rivet version |
 | `--no-git` | skip `git init` |
 | `--pm <name>` | `npm`, `pnpm`, `yarn` or `bun` (default: the one running the command) |
 | `-f`, `--force` | write into a folder that is not empty |
+| `--quiet` | errors only, no questions |
+| `--json` | one JSON result, no questions |
+| `--verbose` | error stacks and successful install output (also `DEBUG=rivet`) |
 | `-h`, `--help` | all options |
 
 With npm, options go after `--`.
 
+Install and git steps show progress and duration. CI/pipes use plain periodic lines; `NO_COLOR` disables color and wins over `FORCE_COLOR`. Exit codes: 0 success, 1 failure (including install/git failure), 2 invalid arguments, 130 cancelled. The created folder remains available after a failed install. `installDependencies()` is asynchronous and returns `Promise<boolean>`.
+
 ## Nx monorepos
 
-The same templates as Nx projects, with cached `build` / `test` / `check` targets: [`@rivetjs/nx`](https://github.com/rivetjs/rivet/tree/main/libs/nx) (`npx create-nx-workspace@latest my-org --preset=@rivetjs/nx`, or `npx nx add @rivetjs/nx` in an existing workspace).
+The same templates as Nx projects, with cached `build` / `test` / `check` targets: [`@rivetjs/nx`](https://github.com/N1XUS/rivetjs/tree/main/libs/nx) (`npx create-nx-workspace@latest my-org --preset=@rivetjs/nx`, or `npx nx add @rivetjs/nx` in an existing workspace).

package/deploy.d.ts

@@ -18,7 +18,7 @@ export declare const DEPLOY_TARGETS: readonly [{
 }, {
     readonly id: "deno";
     readonly label: "Deno";
-    readonly hint: "`deno run dist/server/deno.js` (server template)";
+    readonly hint: "`deno run --allow-net --allow-read --allow-env dist/server/deno.js` (server template)";
 }];
 export type DeployTarget = (typeof DEPLOY_TARGETS)[number]["id"];
 /** Wrangler major the cloudflare target was verified with (`wrangler dev --local`, 4.x). */

package/deploy.js

@@ -15,7 +15,7 @@ export const DEPLOY_TARGETS = [
     { id: "netlify", label: "Netlify", hint: "netlify.toml + Netlify Functions (dist/netlify)" },
     { id: "cloudflare", label: "Cloudflare Workers", hint: "Workers + static assets, `wrangler deploy`" },
     { id: "bun", label: "Bun", hint: "`bun dist/server/bun.js` (server template)" },
-    { id: "deno", label: "Deno", hint: "`deno run dist/server/deno.js` (server template)" },
+    { id: "deno", label: "Deno", hint: "`deno run --allow-net --allow-read --allow-env dist/server/deno.js` (server template)" },
 ];
 /** Wrangler major the cloudflare target was verified with (`wrangler dev --local`, 4.x). */
 export const WRANGLER_RANGE = "^4.0.0";
@@ -78,10 +78,10 @@ export function deployOverlay(target, pm = "npm") {
                 const label = findDeployTarget(target).label;
                 const how = {
                     vercel: `\`${run("build")}\` also writes \`.vercel/output\` (Build Output API). Deploy it with the Vercel CLI: \`${run("deploy")}\` (\`vercel deploy --prebuilt\`).`,
-                    netlify: `\`netlify.toml\` makes Netlify run \`${run("build")}\` and publish \`dist/netlify\`; the server function goes to \`.netlify/v1\`. Connect the repository in Netlify, or deploy with the Netlify CLI after a build.`,
+                    netlify: `\`netlify.toml\` makes Netlify run \`${run("build")}\` and publish \`dist/netlify\`; server-mode builds also put a function in \`.netlify/v1\`. Connect the repository in Netlify, or deploy with the Netlify CLI after a build.`,
                     cloudflare: `\`${run("build")}\` writes \`dist/cloudflare\` (worker + static assets + \`wrangler.json\`). \`${run("preview")}\` runs it in the local Workers runtime, \`${run("deploy")}\` uploads it. Keep \`nodejs_compat\` off (the build sets the compatibility flags).`,
-                    bun: `\`${run("build")}\` writes \`dist/server/bun.js\`; \`${run("start")}\` serves the app with Bun (\`PORT\`, \`HOST\`). Bun must be installed.`,
-                    deno: `\`${run("build")}\` writes \`dist/server/deno.js\`; \`${run("start")}\` serves the app with Deno (\`PORT\`, \`HOST\`). Deno must be installed.`,
+                    bun: `\`${run("build")}\` writes \`dist/server/bun.js\`; \`${run("start")}\` serves the app with Bun (\`PORT\`, \`HOST\`). Bun must be installed. This target removes the Node-only \`serve.js\`, \`Dockerfile\` and \`.dockerignore\`; the earlier Docker instructions do not apply.`,
+                    deno: `\`${run("build")}\` writes \`dist/server/deno.js\`; \`${run("start")}\` serves the app with Deno (\`PORT\`, \`HOST\`). Deno must be installed. This target removes the Node-only \`serve.js\`, \`Dockerfile\` and \`.dockerignore\`; the earlier Docker instructions do not apply.`,
                 };
                 writeFileSync(readme, readFileSync(readme, "utf8").trimEnd() +
                     `\n\n## Deploy: ${label}\n\n- \`vite.config.ts\` sets \`rivetRouter({ adapter: "${target}" })\`.\n- ${how[target]}\n`);

package/index.d.ts

@@ -108,10 +108,12 @@ export declare function createProject(options: CreateOptions): {
     name: string;
     files: string[];
 };
-/** `<pm> install` in `dir` (inherits the terminal). Returns whether it succeeded. */
-export declare function installDependencies(dir: string, pm: PackageManager, { stdio }?: {
-    stdio?: "inherit" | "pipe" | undefined;
-}): boolean;
+/** `<pm> install` in `dir`; asynchronous so the CLI can report progress. */
+export declare function installDependencies(dir: string, pm: PackageManager, { stdio, onOutput, env, }?: {
+    stdio?: "inherit" | "pipe";
+    onOutput?: (text: string) => void;
+    env?: NodeJS.ProcessEnv;
+}): Promise<boolean>;
 /** `git init` + first commit, unless git is missing or `dir` is already inside a work tree. */
 export declare function initGit(dir: string): "created" | "committed" | "inside-repo" | "no-git" | "failed";
 /** `dir` exists and is a file (not a folder). */

package/index.js

@@ -4,7 +4,7 @@
 //
 // Templates: the published package ships them in `templates/` (copied from the repository's `templates/` at
 // package time by `bundle.ts`); inside the repository they are read from `templates/` directly.
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -159,10 +159,18 @@ export function createProject(options) {
     writeFileSync(join(dir, "package.json"), JSON.stringify(pkg, null, 2) + "\n");
     return { dir, name, files: [...files].sort() };
 }
-/** `<pm> install` in `dir` (inherits the terminal). Returns whether it succeeded. */
-export function installDependencies(dir, pm, { stdio = "inherit" } = {}) {
-    const run = spawnSync(pm, pm === "yarn" ? [] : ["install"], { cwd: dir, stdio, shell: process.platform === "win32" });
-    return run.status === 0;
+/** `<pm> install` in `dir`; asynchronous so the CLI can report progress. */
+export async function installDependencies(dir, pm, { stdio = "inherit", onOutput, env = process.env, } = {}) {
+    const child = spawn(pm, pm === "yarn" ? [] : ["install"], { cwd: dir, stdio, env, shell: process.platform === "win32" });
+    child.stdout?.on("data", (chunk) => onOutput?.(String(chunk)));
+    child.stderr?.on("data", (chunk) => onOutput?.(String(chunk)));
+    return new Promise((done) => {
+        child.once("error", (error) => {
+            onOutput?.(error.message);
+            done(false);
+        });
+        child.once("close", (code) => done(code === 0));
+    });
 }
 /** `git init` + first commit, unless git is missing or `dir` is already inside a work tree. */
 export function initGit(dir) {

package/main.d.ts

@@ -4,6 +4,9 @@ export interface MainIO extends PromptIO {
     error: NodeJS.WritableStream;
     cwd: string;
     env: Record<string, string | undefined>;
+    json?: boolean;
+    quiet?: boolean;
+    verbose?: boolean;
 }
-/** Runs the command; resolves with the exit code (0 ok, 1 error, 130 cancelled). */
+/** Runs the command; resolves with the exit code (0 ok, 1 failure, 2 usage, 130 cancelled). */
 export declare function main(argv: string[], io: MainIO): Promise<number>;

package/main.js

@@ -1,7 +1,9 @@
 // The create-rivet command: arguments (node:util parseArgs), questions (./prompt.ts), then ./index.ts does the work.
 //   npm create rivet@latest [dir] [-- --template <id>] [--yes] [--no-install] [--no-git] …
+import { paint as color, progress, suggestion, summary, debugEnabled } from "./output.js";
 import { basename, relative, resolve } from "node:path";
-import { parseArgs, styleText } from "node:util";
+import { Writable } from "node:stream";
+import { parseArgs } from "node:util";
 import { commands, createProject, detectPackageManager, findTemplate, initGit, installDependencies, isEmptyDir, isFile, ownVersion, PACKAGE_MANAGERS, TEMPLATES, toPackageName, validatePackageName, } from "./index.js";
 import { DEPLOY_TARGETS, deployOverlay, deployProblem, findDeployTarget } from "./deploy.js";
 import { closePrompts, confirm, PromptCancelled, select, text } from "./prompt.js";
@@ -20,15 +22,27 @@ Options:
       --git / --no-git           git init + first commit (default: yes)
       --pm <name>         ${PACKAGE_MANAGERS.join(" | ")} (default: the one running create, else npm)
       --rivet-version <spec>     @rivetjs/* dependency spec (default: this release)
+      --quiet             errors only; accept defaults without prompts
+      --json              one JSON result; accept defaults without prompts
+      --verbose           include error stacks and install output (also DEBUG=rivet)
   -f, --force             write into a folder that is not empty
   -h, --help              this text
   -v, --version           create-rivet version
 
+Examples:
+  npm create rivet@latest my-app -- --template server --yes
+  npm create rivet@latest my-app -- --no-install --no-git --json
+
+Exit status: 0 success, 1 failure, 2 usage error, 130 cancelled.
+
 Templates:
 ${TEMPLATES.map((t) => `  ${t.id.padEnd(9)} ${t.label}: ${t.hint}`).join("\n")}
 `;
-/** Runs the command; resolves with the exit code (0 ok, 1 error, 130 cancelled). */
+/** Runs the command; resolves with the exit code (0 ok, 1 failure, 2 usage, 130 cancelled). */
 export async function main(argv, io) {
+    const resultOutput = io.output;
+    io = { ...io, json: argv.includes("--json"), quiet: argv.includes("--quiet"), verbose: argv.includes("--verbose") || debugEnabled(io.env) };
+    const started = performance.now();
     let args;
     try {
         args = parseArgs({
@@ -36,6 +50,9 @@ export async function main(argv, io) {
             allowPositionals: true,
             allowNegative: true,
             options: {
+                quiet: { type: "boolean" },
+                json: { type: "boolean" },
+                verbose: { type: "boolean" },
                 template: { type: "string", short: "t" },
                 deploy: { type: "string", short: "d" },
                 name: { type: "string", short: "n" },
@@ -51,27 +68,62 @@ export async function main(argv, io) {
         });
     }
     catch (error) {
-        io.error.write(`${error.message}\n\n${HELP}`);
-        return 1;
+        const message = error.message;
+        const unknown = /Unknown option '([^']+)'/.exec(message)?.[1];
+        return fail(io, message +
+            (unknown
+                ? suggestion(unknown, [
+                    "--template",
+                    "--deploy",
+                    "--name",
+                    "--yes",
+                    "--install",
+                    "--no-install",
+                    "--git",
+                    "--no-git",
+                    "--pm",
+                    "--rivet-version",
+                    "--force",
+                    "--help",
+                    "--version",
+                    "--quiet",
+                    "--json",
+                    "--verbose",
+                ])
+                : ""), 2);
     }
     const { values, positionals } = args;
-    const paint = (format, value) => styleText(format, value, { stream: io.output });
+    io = { ...io, json: !!values.json, quiet: !!values.quiet, verbose: !!values.verbose || debugEnabled(io.env) };
+    const paint = (format, value) => color(format, value, io.output, io.env);
     if (values.help)
         return (io.output.write(HELP), 0);
     if (values.version)
         return (io.output.write(ownVersion() + "\n"), 0);
     if (positionals.length > 1)
-        return fail(io, `Expected one folder, got ${positionals.join(" ")}`);
+        return fail(io, `Expected one folder, got ${positionals.join(" ")}`, 2);
     if (values.template && !findTemplate(values.template))
-        return fail(io, `Unknown template "${values.template}" (${TEMPLATES.map((t) => t.id).join(", ")})`);
+        return fail(io, `Unknown template "${values.template}" (${TEMPLATES.map((t) => t.id).join(", ")})`, 2);
     if (values.deploy && !findDeployTarget(values.deploy))
-        return fail(io, `Unknown deploy target "${values.deploy}" (${DEPLOY_TARGETS.map((t) => t.id).join(", ")})`);
+        return fail(io, `Unknown deploy target "${values.deploy}" (${DEPLOY_TARGETS.map((t) => t.id).join(", ")})`, 2);
     if (values.pm && !PACKAGE_MANAGERS.includes(values.pm))
-        return fail(io, `Unknown package manager "${values.pm}" (${PACKAGE_MANAGERS.join(", ")})`);
+        return fail(io, `Unknown package manager "${values.pm}" (${PACKAGE_MANAGERS.join(", ")})`, 2);
     if (values.name && validatePackageName(values.name))
-        return fail(io, `--name: ${validatePackageName(values.name)}`);
+        return fail(io, `--name: ${validatePackageName(values.name)}`, 2);
     // Questions only on a terminal and without --yes; otherwise every missing answer takes its default.
-    const ask = !values.yes && Boolean(io.input.isTTY);
+    const ask = !values.yes && !io.quiet && !io.json && !io.env.CI && Boolean(io.input.isTTY);
+    // Keep one result on stdout in JSON mode; status text has a private sink.
+    const diagnosticsIO = io;
+    if (io.quiet || io.json)
+        io = {
+            ...io,
+            output: new Writable({
+                write(_chunk, _encoding, done) {
+                    done();
+                },
+            }),
+        };
+    let warnings = 0, errors = 0;
+    const diagnostics = [];
     try {
         io.output.write(`\n${paint(["bold", "blue"], "create-rivet")} ${paint("dim", "v" + ownVersion())}\n\n`);
         let name = values.name;
@@ -86,10 +138,10 @@ export async function main(argv, io) {
         const dir = resolve(io.cwd, folder);
         name ??= toPackageName(basename(dir));
         if (isFile(dir))
-            return fail(io, `${folder} is a file`);
+            return fail(diagnosticsIO, `${folder} is a file`);
         if (!isEmptyDir(dir) && !values.force) {
             if (!ask)
-                return fail(io, `${folder} is not empty (use --force to write into it)`);
+                return fail(diagnosticsIO, `${folder} is not empty (use --force to write into it)`);
             if (!(await confirm(io, `${folder} is not empty. Write into it anyway (files with the same names are replaced)?`, false)))
                 return cancelled(io);
         }
@@ -100,7 +152,7 @@ export async function main(argv, io) {
                 : "static");
         let deploy = values.deploy;
         if (deploy && deployProblem(deploy, template))
-            return fail(io, deployProblem(deploy, template));
+            return fail(diagnosticsIO, deployProblem(deploy, template), 2);
         if (!deploy && ask) {
             const choices = [
                 { value: "none", label: "None", hint: template === "server" ? "Node server (serve.js, Dockerfile)" : "static files (dist/client)" },
@@ -125,21 +177,67 @@ export async function main(argv, io) {
         const run = commands(pm);
         let installed = false;
         if (install) {
-            io.output.write(`\n${paint("dim", "$ " + run.install)}\n`);
-            installed = installDependencies(dir, pm);
-            if (!installed)
-                io.error.write(paint("yellow", `\n${run.install} failed; run it yourself in ${folder}.\n`));
+            const task = progress(`create-rivet: installing with ${pm}`, { stream: io.output, env: io.env, quiet: io.quiet || io.json });
+            let output = "";
+            try {
+                installed = await installDependencies(dir, pm, {
+                    stdio: "pipe",
+                    env: { ...process.env, ...io.env, NO_COLOR: "1", FORCE_COLOR: "0" },
+                    onOutput(text) {
+                        output = (output + text).slice(-65536);
+                    },
+                });
+            }
+            finally {
+                task.stop(installed ? "Dependencies installed" : "Dependency install failed");
+            }
+            if (!installed) {
+                errors++;
+                diagnostics.push({
+                    severity: "error",
+                    message: `${run.install} failed in ${dir}`,
+                    fix: `Run ${run.install} in ${folder} after addressing the package manager error.`,
+                    details: output,
+                });
+                if (!io.json)
+                    io.error.write(`error: ${run.install} failed in ${dir}.\n  fix: Run ${run.install} in ${folder} and address the package manager error below.\n${output}\n`);
+            }
+            if (installed && io.verbose && !io.json)
+                io.error.write(output);
         }
         if (git) {
-            const result = initGit(dir);
+            const task = progress("create-rivet: initializing git", { stream: io.output, env: io.env, quiet: io.quiet || io.json });
+            let result;
+            try {
+                result = initGit(dir);
+            }
+            finally {
+                task.stop("Git step finished");
+            }
+            if (result === "no-git" || result === "created")
+                warnings++;
+            if (result === "failed")
+                errors++;
+            if (result === "failed" || result === "created" || result === "no-git")
+                diagnostics.push({
+                    severity: result === "failed" ? "error" : "warning",
+                    message: `Git step in ${dir}: ${result}`,
+                    fix: result === "no-git"
+                        ? "Install Git, then run git init in the created folder."
+                        : "Run git status and check git user.name / user.email in the created folder.",
+                });
             if (result === "committed")
                 io.output.write(`${paint("green", "Git")} repository created with a first commit\n`);
             else if (result === "created")
-                io.output.write(`${paint("green", "Git")} repository created (files staged; no commit: set git user.name / user.email)\n`);
+                io.output.write(`${paint("yellow", "warning: Git")} repository created (files staged; commit not created). Run git status and check git user.name / user.email.\n`);
             else if (result === "inside-repo")
                 io.output.write(`${paint("dim", "Git: already inside a repository, skipped")}\n`);
+            else if (result === "failed") {
+                if (!io.json)
+                    io.error.write(`error: Git initialization failed in ${dir}.\n  fix: Run git init and git add in that folder to inspect the failure.\n`);
+            }
             else
-                io.output.write(`${paint("dim", "Git: not available, skipped")}\n`);
+                io.output.write(`${paint("yellow", "warning: Git is not available, skipped; install Git to initialize later.")}\n`);
         }
         const cd = relative(io.cwd, dir) || ".";
         io.output.write(`\nNext:\n`);
@@ -148,20 +246,38 @@ export async function main(argv, io) {
         if (!installed)
             io.output.write(`  ${run.install}\n`);
         io.output.write(`  ${run.run("dev")}\n\n`);
-        return 0;
+        const durationMs = Math.round(performance.now() - started);
+        if (io.json)
+            resultOutput.write(JSON.stringify({
+                directory: dir,
+                template,
+                installed,
+                errors,
+                diagnostics,
+                warnings,
+                durationMs,
+                ...(errors ? { fix: diagnostics.find((diagnostic) => diagnostic.severity === "error").fix } : {}),
+            }) + "\n");
+        else if (!io.quiet)
+            io.output.write(`create-rivet: ${summary(errors, warnings)} in ${(durationMs / 1000).toFixed(1)} s\n`);
+        return errors ? 1 : 0;
     }
     catch (error) {
         if (error instanceof PromptCancelled)
             return cancelled(io);
-        return fail(io, error.message);
+        return fail(diagnosticsIO, error.message, 1, error);
     }
     finally {
         closePrompts(io);
     }
 }
-function fail(io, message) {
-    io.error.write(styleText("red", "Error: ", { stream: io.error }) + message + "\n");
-    return 1;
+function fail(io, message, exitCode = 1, error) {
+    const fix = exitCode === 2 ? "Run create-rivet --help and correct the argument." : "Check the target directory and permissions, then retry.";
+    if (io.json)
+        io.output.write(JSON.stringify({ error: message, fix, exitCode, ...(io.verbose && error instanceof Error ? { stack: error.stack } : {}) }) + "\n");
+    else
+        io.error.write(color("red", "Error: ", io.error, io.env) + message + `\n  fix: ${fix}\n` + (io.verbose && error instanceof Error ? error.stack + "\n" : ""));
+    return exitCode;
 }
 function cancelled(io) {
     io.error.write("Cancelled.\n");

package/output.d.ts

@@ -0,0 +1,24 @@
+import { styleText } from "node:util";
+export interface TerminalStream {
+    isTTY?: boolean;
+    columns?: number;
+    write(text: string): unknown;
+}
+export type TerminalEnv = Record<string, string | undefined>;
+/** CI stays plain even when a wrapper sets FORCE_COLOR. NO_COLOR always wins. */
+export declare function colorEnabled(stream: Pick<TerminalStream, "isTTY">, env?: TerminalEnv): boolean;
+export declare function paint(format: Parameters<typeof styleText>[0], text: string, stream?: TerminalStream, env?: TerminalEnv): string;
+export declare function debugEnabled(env?: TerminalEnv): boolean;
+/** Conservative edit-distance suggestion; never guesses an unrelated command. */
+export declare function suggestion(value: string, choices: readonly string[]): string;
+export declare function summary(errors: number, warnings: number): string;
+/** One updating line on a terminal; periodic plain lines in pipes/CI. Always stop in a finally block. */
+export declare function progress(label: string, { stream, env, quiet, interval, }?: {
+    stream?: TerminalStream;
+    env?: TerminalEnv;
+    quiet?: boolean;
+    interval?: number;
+}): {
+    update(value: string): void;
+    stop(message?: string): void;
+};

package/output.js

@@ -0,0 +1,66 @@
+// Standalone create-rivet presentation: no dependency on the framework/compiler packages.
+import { styleText } from "node:util";
+/** CI stays plain even when a wrapper sets FORCE_COLOR. NO_COLOR always wins. */
+export function colorEnabled(stream, env = process.env) {
+    if (env.NO_COLOR !== undefined || (env.CI !== undefined && env.CI !== "false" && env.CI !== "0") || env.FORCE_COLOR === "0")
+        return false;
+    return env.FORCE_COLOR !== undefined || !!stream.isTTY;
+}
+export function paint(format, text, stream = process.stderr, env = process.env) {
+    return colorEnabled(stream, env) ? styleText(format, text, { validateStream: false }) : text;
+}
+export function debugEnabled(env = process.env) {
+    return (env.DEBUG ?? "").split(/[ ,]+/).some((part) => part === "rivet" || part === "rivet:*" || part === "*");
+}
+/** Conservative edit-distance suggestion; never guesses an unrelated command. */
+export function suggestion(value, choices) {
+    const distance = (a, b) => {
+        let row = Array.from({ length: b.length + 1 }, (_, i) => i);
+        for (let i = 1; i <= a.length; i++) {
+            const next = [i];
+            for (let j = 1; j <= b.length; j++)
+                next[j] = Math.min(next[j - 1] + 1, row[j] + 1, row[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+            row = next;
+        }
+        return row[b.length];
+    };
+    const best = choices.map((choice) => ({ choice, score: distance(value, choice) })).sort((a, b) => a.score - b.score)[0];
+    return best && best.score <= Math.min(3, Math.max(1, Math.floor(value.length / 3))) ? ` Did you mean ${best.choice}?` : "";
+}
+export function summary(errors, warnings) {
+    return `${errors} error${errors === 1 ? "" : "s"}, ${warnings} warning${warnings === 1 ? "" : "s"}`;
+}
+/** One updating line on a terminal; periodic plain lines in pipes/CI. Always stop in a finally block. */
+export function progress(label, { stream = process.stderr, env = process.env, quiet = false, interval = 5000, } = {}) {
+    const start = performance.now();
+    const tty = !!stream.isTTY && !env.CI && env.NO_COLOR === undefined;
+    let detail = "", closed = false;
+    const elapsed = () => `${((performance.now() - start) / 1000).toFixed(1)} s`;
+    const write = () => {
+        if (quiet || closed)
+            return;
+        const line = `${label}${detail ? ": " + detail : ""} (${elapsed()})`.replace(/[\r\n\x1b]/g, " ");
+        stream.write(tty ? `\r\x1b[2K${line.slice(0, Math.max(10, (stream.columns ?? 80) - 1))}` : line + "\n");
+    };
+    write();
+    const timer = quiet ? undefined : setInterval(write, tty ? 100 : interval);
+    timer?.unref();
+    return {
+        update(value) {
+            detail = value;
+        },
+        stop(message) {
+            if (closed)
+                return;
+            closed = true;
+            if (timer)
+                clearInterval(timer);
+            if (!quiet) {
+                if (tty)
+                    stream.write("\r\x1b[2K");
+                if (message)
+                    stream.write(`${message} in ${elapsed()}\n`);
+            }
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-rivet",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.2",
   "license": "MIT",
   "type": "module",
   "description": "Create a Rivet app: npm create rivet@latest",
@@ -52,6 +52,8 @@
     "index.js",
     "main.d.ts",
     "main.js",
+    "output.d.ts",
+    "output.js",
     "prompt.d.ts",
     "prompt.js",
     "templates"

package/prompt.d.ts

@@ -4,6 +4,7 @@ export interface PromptIO {
         setRawMode?: (mode: boolean) => unknown;
     };
     output: NodeJS.WritableStream;
+    env?: Record<string, string | undefined>;
 }
 /** Thrown when the user cancels (Ctrl+C, Ctrl+D / end of input). */
 export declare class PromptCancelled extends Error {

package/prompt.js

@@ -2,14 +2,14 @@
 // TTY, a numbered answer otherwise). Every prompt takes its streams, so tests drive them with PassThrough.
 import { emitKeypressEvents } from "node:readline";
 import { createInterface } from "node:readline/promises";
-import { styleText } from "node:util";
+import { paint } from "./output.js";
 /** Thrown when the user cancels (Ctrl+C, Ctrl+D / end of input). */
 export class PromptCancelled extends Error {
     constructor() {
         super("cancelled");
     }
 }
-const color = (format, text, io) => styleText(format, text, { stream: io.output });
+const color = (format, text, io) => paint(format, text, io.output, io.env);
 const readers = new WeakMap();
 /** One line reader per input stream (a reader per question would drop lines buffered after the first). */
 function reader(io) {

package/templates/starter-minimal/.agents/skills/rivet-add-route/SKILL.md

@@ -1,23 +1,23 @@
 ---
 name: rivet-add-route
-description: "Add a page or endpoint to a Rivet app with file routes, server data (serverLoad), actions, head and layouts. Use when the user asks for a new page, URL, route, endpoint or loader in a Rivet project."
+description: "Add a page or endpoint to a Rivet app with file routes, server data (load(…)), actions, head and layouts. Use when the user asks for a new page, URL, route, endpoint or loader in a Rivet project."
 ---
 
 <!-- Generated by libs/mcp/ai/sync.ts from libs/mcp/ai/skills/add-route.md in the Rivet repository: edit the source there and run the script. In an app created from a starter this file is yours to edit. -->
 
 # Add a route to a Rivet app
 
-1. Pick the file under `src/routes/` (URL = path): `about.tsx` → `/about`, `blog/[slug].tsx` → `/blog/:slug`, `docs/[[lang]]/x.tsx` (optional param), `files/[...path].tsx` (rest), `(group)/p.tsx` → `/p` (shares the group's `_layout.tsx`), `api/time.ts` → endpoint (`export const onGet = () => Response.json(…)`). `_layout.tsx` wraps its folder; `_404.tsx` / `_error.tsx` handle misses / errors. Look up details with `get_doc("docs:/guides/routing/file-routes/")`.
-2. Write the page. Server code lives in `server…` exports (stripped from the browser build):
+1. Pick the file under `src/routes/` (URL = path): `about.tsx` → `/about`, `blog/[slug].tsx` → `/blog/:slug`, `docs/[[lang]]/x.tsx` (optional param), `files/[...path].tsx` (rest), `(group)/p.tsx` → `/p` (shares the group's `_layout.tsx`), `api/time.ts` → endpoint (`export const GET = onGet(() => Response.json(…))`, `onGet` from `@rivetjs/router`). `_layout.tsx` wraps its folder; `_404.tsx` / `_error.tsx` handle misses / errors. Look up details with `get_doc("docs:/guides/routing/file-routes/")`.
+2. Write the page. Server code lives in exports wrapped in a `@rivetjs/router` call — `load(…)`, `actions(…)`, `guard(…)`, `onGet(…)` … (stripped from the browser build):
 
 ```tsx
-import { notFound, type PageProps, type RequestEvent } from "@rivetjs/router";
+import { notFound, type PageProps, type RequestEvent, load } from "@rivetjs/router";
 
-export const serverLoad = async ({ params }: RequestEvent<"blog/[slug]">) => {
+export const loader = load(async ({ params }: RequestEvent<"blog/[slug]">) => {
   const post = await findPost(params.slug); // server-only: database, files, secrets
   if (!post) throw notFound();
   return { post };
-};
+});
 
 export const head = { title: "Post" };
 
@@ -27,10 +27,10 @@ export default function Post({ data }: PageProps<"blog/[slug]">) {
 ```
 
 - Page props `data`, `params`, `url` are plain values; in `_layout.tsx` (`LayoutProps`) they are accessors: `data()`, `params()`, `url()`, plus `children`.
-- Mutations: `export const serverActions = { name: async ({ request }) => … }` + `<form method="post" action="?/name">`; with validation use `@rivetjs/forms` (`action(def, fn)` from `@rivetjs/forms/server`).
-- Access checks: `serverGuard` (throw / return `redirect()`, `deny()`, `notFound()`).
-- Static mode (`rivetRouter({ mode: "static" })`): `serverLoad` runs at build time; dynamic `[param]` pages list their params in `serverEntries`.
+- Mutations: `export const forms = actions({ name: async ({ request }) => … })` + `<form method="post" action="?/name">`; with validation use `@rivetjs/forms` (`action(def, fn)` from `@rivetjs/forms/server`).
+- Access checks: `guard(…)` (throw / return `redirect()`, `deny()`, `notFound()`).
+- Static mode (`rivetRouter({ mode: "static" })`): `load(…)` runs at build time; dynamic `[param]` pages list their params in `entries(…)`.
 - Server-only helpers go in `*.server.ts` files (browser code cannot import them: RV3008).
 
-3. Link to it: plain `<a href="/blog/hello">` (client navigation), or typed `<Link to="/blog/hello">` from `@rivetjs/router/link`; programmatic `navigate()` from `@rivetjs/router/client`.
+3. Link to it: plain `<a href="/blog/hello">` (client navigation when the page has the client router; document navigation otherwise), or typed `<Link to="/blog/hello">` from `@rivetjs/router/link`; programmatic `navigate()` from `@rivetjs/router/client`.
 4. Run `npm run check` (`rivet sync` regenerates the typed routes in `.rivet/`, `rivet-check` reports `RV` codes; RV3101 = a link matches no route). Fix every diagnostic (`explain_diagnostic(code)`), then `npm run build`.

package/templates/starter-minimal/.agents/skills/rivet-fix-resumability-error/SKILL.md

@@ -1,26 +1,21 @@
 ---
 name: rivet-fix-resumability-error
-description: 'Diagnose and fix Rivet resumability errors - RV2xxx compiler diagnostics, RV1016 handler errors, "is not serializable" / "Cannot resume" build or prerender errors, browser globals during server rendering, state that resets after the first click. Use when a Rivet build, check or page fails with such an error.'
+description: "Diagnose and fix Rivet resumability errors - RV2xxx compiler diagnostics, RV1016 handler errors, RV2107 route data warnings, browser globals during server rendering, a component that renders in the browser instead of resuming. Use when a Rivet build, check or page fails with such an error."
 ---
 
 <!-- Generated by libs/mcp/ai/sync.ts from libs/mcp/ai/skills/fix-resumability-error.md in the Rivet repository: edit the source there and run the script. In an app created from a starter this file is yours to edit. -->
 
 # Fix a resumability error
 
-A Rivet page is rendered on the server and resumed in the browser: handlers, bindings and client effects run there with the values they capture, which the server serialized into the HTML. Errors come from code that cannot cross that line.
+A Rivet page is rendered on the server and resumed in the browser: the first time a component is used, the browser runs its code once over the server HTML, starting from the signal values the server wrote. Errors come from code that renders differently on the two sides or from state/data that cannot be written into the page. Keep signal/store values as plain JSON data; the richer resume-format encoding (including registered classes) applies to route data.
 
 1. Get the exact diagnostic: `npm run check` (`file:line:col - error RVnnnn`), the Vite overlay (`[RVnnnn] file:line:col`), or `check_code(source, filename)`. For the fix: `explain_diagnostic("RVnnnn")`; `check_code` also returns the quick-fixed source when one applies.
 2. Common codes:
    - RV2001 browser global (`window`, `document`, `localStorage`) read during server rendering → move it into a handler, `clientEffect(() => …)`, `clientEvent(window, "resize", …)` or `clientOnly(() => import("…"))`.
-   - RV2003 captured class instance (`new Intl.NumberFormat`, an SDK client) → capture plain data; create the object inside the handler or `clientEffect`, or build it with `reconstruct(() => new X(…))` from `@rivetjs/runtime/dom` (the browser runs the factory on first read). A data class declared in the component module (plain fields) resumes as is.
-   - RV2102 captured instance of a module class that cannot resume as data (`#private` field, a decorator, a field arrow using `super`, a base that is not a data class of the module, `window` / `document` / `WebSocket` read while constructing) → create it inside the handler, build it with `reconstruct(() => new X(…))`, keep only plain fields, or add `[serialize]()` + `static [revive](data)` (from `@rivetjs/runtime/resume-format`; package classes: `registerClass(Cls, { id, serialize, revive })` in a module imported by the server code and the resume entry). At render, `RV2102: X has [serialize] but no static [revive]` → add the `static [revive]`.
    - RV1016 handler expression reads state when it binds (`onClick={a() ? f : g}`) → wrap: `onClick={(e) => (a() ? f(e) : g(e))}`.
-   - RV2002 ref callback must assign a local → `ref={(el) => (local = el)}` or `const el = ref()` + `ref={el}`.
-   - RV2006 JSX inside a handler / effect / computed → render JSX in the component, switch it with a signal.
-   - RV2007 `this` in resumable code → `event.currentTarget`.
-   - RV2009 two module references share a browser name (two imports of different modules under one name) → rename one import (`import { fmt as fmtDate } from …`).
-   - RV2101 (warning, type-aware) a captured value's type does not serialize → as RV2003.
-3. Build / prerender error `Cannot resume <file>#<Component>$<hash>: function is not serializable` (dev server: ``capture `<name>` function is not serializable``; dev build: `capture #<i> …`): a captured function Rivet did not compile (created at runtime by a library such as `memoize(fn)`, a `.bind(…)` written inside an object literal (keep `const inc = add.bind(null, 2)` in a local constant and store `inc`; `.bind(ctx)` of a function using `this` stays RV2007), a method, or held by an object built outside a component: at module level such as `const table = { format: formatEuro }`, or by your own hook / helper such as `function useFormat() { return { format: formatEuro }; }`). Wrap it in an inline arrow, or build the object inside the component (module-level and imported functions used by name there resume by reference). A library object holding functions (a chart, editor, socket client from a package): build it with `reconstruct(() => createChart(…))` from `@rivetjs/runtime/dom` — no value in the page, the browser runs the factory on first read (module level: one server instance per process, never read request state in it). A class instance at render (`X instance is not serializable`): your class → `reconstruct(() => new X(…))` or `[serialize]()` + `static [revive](data)`; a package class → `registerClass(X, { id, serialize, revive })` from `@rivetjs/runtime/resume-format`. `NODE_ENV=development vite build` names the value path. Rules: `get_doc("docs:/best-practices/serializable-captures/")`.
-4. State resets on the first change after resume: a child destructures its props (`function C({ value })`) and is re-created → read `props.value`. Copies of `props.children` in a local are not tracked → render `{props.children}` directly.
+   - RV2103 render is not deterministic (`Date.now()`, `Math.random()`, `crypto.randomUUID()` read while rendering) → keep the value in keyed state (`signal(Date.now())`) or read it in a handler / `clientEffect`.
+   - RV2104 (warning) keyed state created in a loop → create one signal / store outside the loop and keep the per-item values in it.
+3. RV2107 (runtime warning) route data not encodable: a loader / action / error value holds a function, symbol, promise or an instance of an unregistered class; the page renders on the server but cannot resume. Return plain data; for a class use `registerClass(X, { id, serialize, revive })` from `@rivetjs/runtime/resume-format`, imported on server and browser.
+4. Dev warning that a component's markup differs and it renders in the browser: its render reads something that differs between server and browser (a browser global, a time, a random value, data the browser loads differently) → keep it in a signal, or move it into a `clientEffect`.
 5. `.ts` module importing `@rivetjs/runtime/dom` (bundles the DOM runtime into SSR) → move that code into a `.tsx` file.
-6. Re-run `npm run check` and `npm run build` (prerender exercises serialization); both must be clean.
+6. Re-run `npm run check` and `npm run build`; both must be clean.