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

package/README.md

@@ -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/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.1",
+  "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

@@ -32,5 +32,5 @@ export default function Post({ data }: PageProps<"blog/[slug]">) {
 - 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.

package/templates/starter-minimal/.agents/skills/rivet-port-react-component/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rivet-port-react-component
-description: "Port a React (or Solid / Next.js) component or page to Rivet idioms - signals instead of useState, clientEffect instead of useEffect, For with a key, live props, class, serializable handlers. Use when the user pastes React code or asks to convert / migrate a component to Rivet."
+description: "Port a React (or Solid / Next.js) component or page to Rivet idioms - signals instead of useState, clientEffect instead of useEffect, For with a key, live props, class, ordinary function handlers. Use when the user pastes React code or asks to convert / migrate a component to Rivet."
 ---
 
 <!-- Generated by libs/mcp/ai/sync.ts from libs/mcp/ai/skills/port-react-component.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. -->
@@ -30,7 +30,7 @@ Map each construct (full table: `get_doc("docs:/start/coming-from-other-framewor
 Then fix what resuming requires:
 
 1. Move browser reads (`window`, `document`, `localStorage`, `matchMedia`) out of the component body into handlers or `clientEffect` (RV2001).
-2. Handlers: inline arrows or local consts. Values they capture must serialize: create class instances (`Intl.*`, SDK clients) inside the handler or build them with `reconstruct(() => new X(…))` (`import { reconstruct } from "@rivetjs/runtime/dom"`; RV2003); wrap library callbacks: `onPress={() => track("save")}`.
+2. Handlers: plain functions (inline arrows, local consts, imported functions); nothing they use needs to serialize. Keep values that differ between server and browser (`Date.now()`, random ids) in a signal or a handler.
 3. Render props and item renderers stay functions (`{(item) => …}`).
 4. Third-party React UI → `@rivetjs/ui` / `@rivetjs/cdk` equivalents: `list_components`, `get_component(name)`; React Aria-style names carry over (`onPress`, `isOpen={signal}`).
 5. `check_code` the result, fix every RV code (`explain_diagnostic`), then `npm run check`.

package/templates/starter-minimal/.agents/skills/rivet-ui-design/references/component-composition.md

@@ -40,13 +40,13 @@ Avoid nested interactive targets: an entire clickable card with nested buttons,
 
 **Collection page:** heading + main create action → labeled search/filter controls → result count and collection → pagination. Show bulk actions only when selection exists; `ActionBar` or `Toolbar` may fit. Align filters and table columns to the same content edges. Provide initial-empty and filtered-empty states separately.
 
-**Settings page:** heading/description → grouped `Fieldset` sections → controls/help/errors → save feedback/actions. Group related rows within a section with consistent spacing or separators. Do not wrap every preference in a card. Choose either explicit save or immediate updates for a region and make that behavior visible.
+**Settings page:** heading/description → grouped `Fieldset` sections → controls/help/errors → save feedback/actions. Group related rows within a section with consistent spacing or separators; `CellSwitch`, `CellSelect` and `CellSlider` are full-row settings cells. Do not wrap every preference in a card. Choose either explicit save or immediate updates for a region and make that behavior visible.
 
 **Detail/edit page:** summary and status → related content sections → contextual actions. Use a drawer for short contextual edits, a page for long/deep edits, and inline editing for small well-bounded values. Destructive actions belong near the affected object with clear labels and proportionate confirmation.
 
-**Dashboard:** lead with metrics that support a decision, then the trend or collection needed to act. `Kpi`, `TrendChip`, and the chart exports may fit. Every chart needs a readable explanation or data alternative; meaningful units, time range and empty states matter more than decorative chart variety.
+**Dashboard:** lead with metrics that support a decision, then the trend or collection needed to act. `Kpi`, `KpiGroup`, `Widget`, `NumberValue`, `TrendChip`, and the chart exports may fit; `ItemCard` / `ItemCardGroup` for settings rows, `Timeline` for activity history. Every chart needs a readable explanation or data alternative; meaningful units, time range and empty states matter more than decorative chart variety.
 
-**Command picker:** compose a labeled search field and a supported action collection, often using `Autocomplete` + `Menu` for commands. Confirm documented filtering, virtual focus and activation behavior for the installed version. A command menu and a value-selecting list box are different tasks. A dialog may provide a focused enclosing surface. Add pending, no-match, error and clear-query behavior; do not invent a `Command` export or manual arrow-key loop when suitable primitives exist.
+**Command picker:** `Command` (`@rivetjs/ui/command`) is the modal palette: a search field filtering grouped commands with virtual focus, Enter to run, Escape to clear then close; put extra search words in each item's `textValue`. For an inline picker, compose a labeled search field with `Autocomplete` + `Menu`. A command menu and a value-selecting list box are different tasks. Add pending, no-match, error and clear-query behavior; do not write a manual arrow-key loop. For actions on a right click, use `ContextMenu`.
 
 ## Reuse at the pattern boundary