create-rivet 0.0.0-stage → 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Denys Severyn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# create-rivet
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Create a [Rivet](https://github.com/N1XUS/rivetjs) app.
+
+```sh
+npm create rivet@latest my-app
+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`.
+
+## Templates
+
+| `--template` | What you get |
+| --- | --- |
+| `static` (default) | Static site: pages prerendered to HTML, Tailwind CSS, two routes, an interactive counter. |
+| `server` | Node.js server: a loader and a form action per request, Tailwind CSS, a Dockerfile. |
+| `ui` | Static site with `@rivetjs/ui` components and Tailwind CSS v4. |
+| `minimal` | One page, one signal, no Tailwind. |
+
+All templates use TypeScript and need Node.js 24 or newer.
+
+## Options
+
+```sh
+npm create rivet@latest my-app -- --template server --yes --no-git
+```
+
+| Option | |
+| --- | --- |
+| `-t`, `--template <id>` | `static`, `server`, `ui` or `minimal` |
+| `-d`, `--deploy <target>` | `vercel`, `netlify`, `cloudflare` (any template), `bun`, `deno` (`server` template): sets the router adapter and the platform files |
+| `-n`, `--name <name>` | `package.json` name (default: the folder name) |
+| `-y`, `--yes` | ask nothing, take the defaults |
+| `--no-install` | skip installing dependencies |
+| `--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 |
+| `-h`, `--help` | all options |
+
+With npm, options go after `--`.
+
+## 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/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/cli.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// `create-rivet` bin (`npm create rivet@latest`): see ./main.ts.
+import { main } from "./main.js";
+process.exitCode = await main(process.argv.slice(2), {
+    input: process.stdin,
+    output: process.stdout,
+    error: process.stderr,
+    cwd: process.cwd(),
+    env: process.env,
+});

package/deploy.d.ts

@@ -0,0 +1,32 @@
+import { type Overlay, type PackageManager, type TemplateId } from "./index.js";
+export declare const DEPLOY_TARGETS: readonly [{
+    readonly id: "vercel";
+    readonly label: "Vercel";
+    readonly hint: "Build Output API (.vercel/output), `vercel deploy --prebuilt`";
+}, {
+    readonly id: "netlify";
+    readonly label: "Netlify";
+    readonly hint: "netlify.toml + Netlify Functions (dist/netlify)";
+}, {
+    readonly id: "cloudflare";
+    readonly label: "Cloudflare Workers";
+    readonly hint: "Workers + static assets, `wrangler deploy`";
+}, {
+    readonly id: "bun";
+    readonly label: "Bun";
+    readonly hint: "`bun dist/server/bun.js` (server template)";
+}, {
+    readonly id: "deno";
+    readonly label: "Deno";
+    readonly hint: "`deno run 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). */
+export declare const WRANGLER_RANGE = "^4.0.0";
+export declare function findDeployTarget(id: string): (typeof DEPLOY_TARGETS)[number] | undefined;
+/** Why `target` cannot be used with `template`, or `undefined`. */
+export declare function deployProblem(target: DeployTarget, template: TemplateId): string | undefined;
+/** `rivetRouter({ … })` / `rivetRouter()` → with `adapter: "<target>"` first. Throws when the call is missing. */
+export declare function addAdapter(config: string, target: DeployTarget): string;
+/** The overlay for `target` (package manager: the build command written into netlify.toml). */
+export declare function deployOverlay(target: DeployTarget, pm?: PackageManager): Overlay;

package/deploy.js

@@ -0,0 +1,99 @@
+// `--deploy <target>`: the per-platform edits over a starter, as a create-rivet `Overlay`. The router builds the
+// platform output itself (`rivetRouter({ adapter })`, libs/router/adapters/CLAUDE.md); here only the project files:
+// - every target: `adapter: "<target>"` in vite.config.ts' `rivetRouter({ … })`, `.vercel/` `.netlify/` `.wrangler/`
+//   in .gitignore;
+// - vercel: `deploy` = `vercel deploy --prebuilt` (deploys `.vercel/output` from `npm run build`);
+// - netlify: netlify.toml (build command, `publish = "dist/netlify"`: the Frameworks API has no publish setting);
+// - cloudflare: `wrangler` dev dependency, `preview` = `wrangler dev`, `deploy` = `wrangler deploy` (the build writes
+//   dist/cloudflare/wrangler.json and points Wrangler at it). No `nodejs_compat` flag: the build sets the flags;
+// - bun / deno (server starter only): `start` runs the generated server entry; the Node-only serve.js + Dockerfile go.
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { commands } from "./index.js";
+export const DEPLOY_TARGETS = [
+    { id: "vercel", label: "Vercel", hint: "Build Output API (.vercel/output), `vercel deploy --prebuilt`" },
+    { 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)" },
+];
+/** Wrangler major the cloudflare target was verified with (`wrangler dev --local`, 4.x). */
+export const WRANGLER_RANGE = "^4.0.0";
+const SERVER_ONLY = new Set(["bun", "deno"]);
+const IGNORED = [".vercel/", ".netlify/", ".wrangler/"];
+export function findDeployTarget(id) {
+    return DEPLOY_TARGETS.find((target) => target.id === id);
+}
+/** Why `target` cannot be used with `template`, or `undefined`. */
+export function deployProblem(target, template) {
+    if (SERVER_ONLY.has(target) && template !== "server")
+        return `--deploy ${target} runs a server: use --template server`;
+    return undefined;
+}
+/** `rivetRouter({ … })` / `rivetRouter()` → with `adapter: "<target>"` first. Throws when the call is missing. */
+export function addAdapter(config, target) {
+    if (/rivetRouter\(\s*\{[^}]*\badapter\s*:/.test(config))
+        throw new Error("vite.config.ts already sets an adapter");
+    if (/rivetRouter\(\s*\)/.test(config))
+        return config.replace(/rivetRouter\(\s*\)/, `rivetRouter({ adapter: "${target}" })`);
+    if (/rivetRouter\(\s*\{/.test(config))
+        return config.replace(/rivetRouter\(\s*\{\s*/, `rivetRouter({ adapter: "${target}", `);
+    throw new Error("vite.config.ts has no rivetRouter() call to add the adapter to");
+}
+/** The overlay for `target` (package manager: the build command written into netlify.toml). */
+export function deployOverlay(target, pm = "npm") {
+    return {
+        name: "deploy-" + target,
+        manifest: (pkg) => {
+            const scripts = { ...(pkg["scripts"] ?? {}) };
+            const out = { ...pkg, scripts };
+            if (target === "vercel")
+                scripts["deploy"] = "vercel deploy --prebuilt";
+            if (target === "cloudflare") {
+                scripts["preview"] = "wrangler dev";
+                scripts["deploy"] = "wrangler deploy";
+                out.devDependencies = { ...pkg.devDependencies, wrangler: WRANGLER_RANGE };
+            }
+            if (target === "bun")
+                scripts["start"] = "bun dist/server/bun.js";
+            if (target === "deno")
+                scripts["start"] = "deno run --allow-net --allow-read --allow-env dist/server/deno.js";
+            return out;
+        },
+        edit: (dir) => {
+            const written = ["vite.config.ts", ".gitignore"];
+            const removed = [];
+            const config = join(dir, "vite.config.ts");
+            writeFileSync(config, addAdapter(readFileSync(config, "utf8"), target));
+            const gitignore = join(dir, ".gitignore");
+            const lines = existsSync(gitignore) ? readFileSync(gitignore, "utf8").split("\n").filter(Boolean) : [];
+            writeFileSync(gitignore, [...lines, ...IGNORED.filter((entry) => !lines.includes(entry))].join("\n") + "\n");
+            if (target === "netlify") {
+                writeFileSync(join(dir, "netlify.toml"), `[build]\n  command = "${commands(pm).run("build")}"\n  publish = "dist/netlify"\n`);
+                written.push("netlify.toml");
+            }
+            const readme = join(dir, "README.md");
+            if (existsSync(readme)) {
+                const run = commands(pm).run;
+                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.`,
+                    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.`,
+                };
+                writeFileSync(readme, readFileSync(readme, "utf8").trimEnd() +
+                    `\n\n## Deploy: ${label}\n\n- \`vite.config.ts\` sets \`rivetRouter({ adapter: "${target}" })\`.\n- ${how[target]}\n`);
+                written.push("README.md");
+            }
+            if (SERVER_ONLY.has(target))
+                for (const file of ["serve.js", "Dockerfile", ".dockerignore"])
+                    if (existsSync(join(dir, file))) {
+                        rmSync(join(dir, file));
+                        removed.push(file);
+                    }
+            return { written, removed };
+        },
+    };
+}

package/index.d.ts

@@ -0,0 +1,118 @@
+/** Starter templates offered by the CLI (`--template <id>`); `dir` is the folder under `templates/`. */
+export declare const TEMPLATES: readonly [{
+    readonly id: "static";
+    readonly dir: "starter-static";
+    readonly label: "Static site";
+    readonly hint: "pages prerendered to HTML, Tailwind, two routes, a counter";
+}, {
+    readonly id: "server";
+    readonly dir: "starter-server";
+    readonly label: "Node server";
+    readonly hint: "loader + form action per request, Tailwind, Dockerfile";
+}, {
+    readonly id: "ui";
+    readonly dir: "starter-ui";
+    readonly label: "UI components";
+    readonly hint: "@rivetjs/ui components + Tailwind v4, static";
+}, {
+    readonly id: "minimal";
+    readonly dir: "starter-minimal";
+    readonly label: "Minimal";
+    readonly hint: "one page, one signal, no Tailwind";
+}];
+export type TemplateId = (typeof TEMPLATES)[number]["id"];
+export declare const PACKAGE_MANAGERS: readonly ["npm", "pnpm", "yarn", "bun"];
+export type PackageManager = (typeof PACKAGE_MANAGERS)[number];
+/** This package's own manifest version: every `@rivetjs/*` package is released with the same version. */
+export declare function ownVersion(): string;
+/** The dependency range written for `@rivetjs/*`: exact for a prerelease (`0.1.0-alpha.1`), `^x.y.z` otherwise. */
+export declare function versionRange(version: string): string;
+/** Where the templates are: bundled next to the code (published package) or the repository's `templates/`. */
+export declare function templatesRoot(): string;
+/** `templates/_<name>` (an overlay's files), bundled or in the repository. */
+export declare function overlayDir(name: string): string;
+export declare function findTemplate(name: string): (typeof TEMPLATES)[number] | undefined;
+/** The package manager that runs us (`npm create` / `pnpm create` / `yarn create` / `bun create` set the user agent). */
+export declare function detectPackageManager(userAgent?: string): PackageManager;
+/** Commands shown after creation for a package manager. */
+export declare function commands(pm: PackageManager): {
+    install: string;
+    run: (script: string) => string;
+};
+/** An npm package name from a folder name (`My App` → `my-app`). */
+export declare function toPackageName(name: string): string;
+/** `undefined` when `name` is a valid npm package name, else why not. */
+export declare function validatePackageName(name: string): string | undefined;
+/** True when `dir` is missing or holds nothing but `.git` / `.DS_Store`. */
+export declare function isEmptyDir(dir: string): boolean;
+/** Template paths never copied: build output, installs, generated route types, StackBlitz config. */
+export declare const SKIP: RegExp;
+/** npm never packs `.gitignore` files: the bundled templates carry them as `_gitignore`. */
+export declare const RENAMES: Readonly<Record<string, string>>;
+/** One file of a template (or overlay) folder: `path` relative to the folder (posix, {@link RENAMES} applied). */
+export interface TemplateFile {
+    path: string;
+    /** Absolute source path. */
+    source: string;
+}
+/**
+ * The files of a template (or overlay) folder, sorted: skips {@link SKIP}, applies {@link RENAMES}. Shared by
+ * {@link copyTemplateDir} and `@rivetjs/nx` (which writes them into an Nx `Tree` instead of the file system).
+ */
+export declare function templateFiles(from: string): TemplateFile[];
+/** Copies a template (or an overlay) folder onto `to`: skips {@link SKIP}, applies {@link RENAMES}. */
+export declare function copyTemplateDir(from: string, to: string): string[];
+export interface PackageJson {
+    name?: string;
+    version?: string;
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    [field: string]: unknown;
+}
+/**
+ * The template's `package.json` for the new project: `name`, `version` 0.1.0, every `@rivetjs/*` (and `create-rivet`)
+ * dependency → `range` (templates name `experimental` / `workspace:` / `file:` / `link:` specs that only resolve in the repo).
+ */
+export declare function rewriteManifest(pkg: PackageJson, name: string, range: string): PackageJson;
+/**
+ * Extension point for options layered over a template (e.g. a deploy target, `--deploy`): files copied over the
+ * template (`dir`, same skip / rename rules; keep them in `templates/_<name>/`, which `bundle.ts` ships and
+ * {@link overlayDir} finds), then `manifest` edits the new `package.json` (scripts, dependencies), then `edit`
+ * changes other files in place (`deploy.ts`: vite.config.ts, .gitignore, netlify.toml).
+ */
+export interface Overlay {
+    name: string;
+    dir?: string;
+    manifest?: (pkg: PackageJson) => PackageJson;
+    /** Edits files of the new project (after `dir`); returns the paths it wrote (relative) and removed. */
+    edit?: (dir: string) => {
+        written?: string[];
+        removed?: string[];
+    };
+}
+export interface CreateOptions {
+    /** Target folder (created). */
+    dir: string;
+    template: TemplateId;
+    /** `package.json` name (default: from the folder name). */
+    name?: string;
+    /** `@rivetjs/*` dependency spec (default: {@link versionRange} of this package's version). */
+    rivetVersion?: string;
+    overlays?: Overlay[];
+    /** Templates folder (default {@link templatesRoot}). */
+    templates?: string;
+}
+/** Writes the project. Throws when the template is unknown. Does not install or run git. */
+export declare function createProject(options: CreateOptions): {
+    dir: string;
+    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;
+/** `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). */
+export declare function isFile(path: string): boolean;

package/index.js

@@ -0,0 +1,184 @@
+// create-rivet: copies a Rivet starter template into a new folder, rewrites its `@rivetjs/*` dependencies to
+// the published version, writes the package name, then optionally installs dependencies and runs `git init`.
+// `cli.ts` parses the command line and asks the questions; everything here is plain functions (tests call them).
+//
+// 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 { 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";
+const HERE = dirname(fileURLToPath(import.meta.url));
+/** Starter templates offered by the CLI (`--template <id>`); `dir` is the folder under `templates/`. */
+export const TEMPLATES = [
+    { id: "static", dir: "starter-static", label: "Static site", hint: "pages prerendered to HTML, Tailwind, two routes, a counter" },
+    { id: "server", dir: "starter-server", label: "Node server", hint: "loader + form action per request, Tailwind, Dockerfile" },
+    { id: "ui", dir: "starter-ui", label: "UI components", hint: "@rivetjs/ui components + Tailwind v4, static" },
+    { id: "minimal", dir: "starter-minimal", label: "Minimal", hint: "one page, one signal, no Tailwind" },
+];
+export const PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"];
+/** This package's own manifest version: every `@rivetjs/*` package is released with the same version. */
+export function ownVersion() {
+    return JSON.parse(readFileSync(join(HERE, "package.json"), "utf8")).version;
+}
+/** The dependency range written for `@rivetjs/*`: exact for a prerelease (`0.1.0-alpha.1`), `^x.y.z` otherwise. */
+export function versionRange(version) {
+    return version.includes("-") ? version : "^" + version;
+}
+/** Where the templates are: bundled next to the code (published package) or the repository's `templates/`. */
+export function templatesRoot() {
+    const bundled = join(HERE, "templates");
+    return existsSync(bundled) ? bundled : resolve(HERE, "../../templates");
+}
+/** `templates/_<name>` (an overlay's files), bundled or in the repository. */
+export function overlayDir(name) {
+    return join(templatesRoot(), "_" + name);
+}
+export function findTemplate(name) {
+    return TEMPLATES.find((template) => template.id === name || template.dir === name);
+}
+/** The package manager that runs us (`npm create` / `pnpm create` / `yarn create` / `bun create` set the user agent). */
+export function detectPackageManager(userAgent = process.env["npm_config_user_agent"] ?? "") {
+    const name = userAgent.split("/")[0];
+    return PACKAGE_MANAGERS.includes(name ?? "") ? name : "npm";
+}
+/** Commands shown after creation for a package manager. */
+export function commands(pm) {
+    return {
+        install: pm === "yarn" ? "yarn" : `${pm} install`,
+        run: (script) => (pm === "npm" || pm === "bun" ? `${pm} run ${script}` : `${pm} ${script}`),
+    };
+}
+/** An npm package name from a folder name (`My App` → `my-app`). */
+export function toPackageName(name) {
+    return (name
+        .trim()
+        .toLowerCase()
+        .replace(/\s+/g, "-")
+        .replace(/^[._]+/, "")
+        .replace(/[^a-z0-9~._-]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "rivet-app");
+}
+/** `undefined` when `name` is a valid npm package name, else why not. */
+export function validatePackageName(name) {
+    if (!name)
+        return "Name is empty";
+    if (name.length > 214)
+        return "Name is longer than 214 characters";
+    if (!/^(?:@[a-z0-9~-][a-z0-9._~-]*\/)?[a-z0-9~-][a-z0-9._~-]*$/.test(name))
+        return "Use lowercase letters, digits, '-', '.', '_' (npm package name rules)";
+    return undefined;
+}
+/** True when `dir` is missing or holds nothing but `.git` / `.DS_Store`. */
+export function isEmptyDir(dir) {
+    if (!existsSync(dir))
+        return true;
+    return readdirSync(dir).every((entry) => entry === ".git" || entry === ".DS_Store");
+}
+/** Template paths never copied: build output, installs, generated route types, StackBlitz config. */
+export const SKIP = /(^|[/\\])(node_modules|dist|\.rivet|\.stackblitzrc)([/\\]|$)/;
+/** npm never packs `.gitignore` files: the bundled templates carry them as `_gitignore`. */
+export const RENAMES = { _gitignore: ".gitignore" };
+/**
+ * The files of a template (or overlay) folder, sorted: skips {@link SKIP}, applies {@link RENAMES}. Shared by
+ * {@link copyTemplateDir} and `@rivetjs/nx` (which writes them into an Nx `Tree` instead of the file system).
+ */
+export function templateFiles(from) {
+    const files = [];
+    const walk = (at) => {
+        for (const entry of readdirSync(at, { withFileTypes: true })) {
+            const path = join(at, entry.name);
+            const rel = relative(from, path);
+            if (SKIP.test(rel))
+                continue;
+            if (entry.isDirectory()) {
+                walk(path);
+                continue;
+            }
+            files.push({
+                path: join(dirname(rel), RENAMES[entry.name] ?? entry.name)
+                    .split(sep)
+                    .join("/"),
+                source: path,
+            });
+        }
+    };
+    walk(from);
+    return files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+/** Copies a template (or an overlay) folder onto `to`: skips {@link SKIP}, applies {@link RENAMES}. */
+export function copyTemplateDir(from, to) {
+    const copied = [];
+    for (const file of templateFiles(from)) {
+        const target = join(to, file.path);
+        mkdirSync(dirname(target), { recursive: true });
+        cpSync(file.source, target);
+        copied.push(relative(to, target).split(sep).join("/"));
+    }
+    return copied.sort();
+}
+/**
+ * The template's `package.json` for the new project: `name`, `version` 0.1.0, every `@rivetjs/*` (and `create-rivet`)
+ * dependency → `range` (templates name `experimental` / `workspace:` / `file:` / `link:` specs that only resolve in the repo).
+ */
+export function rewriteManifest(pkg, name, range) {
+    const out = { ...pkg, name, version: "0.1.0" };
+    for (const field of ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]) {
+        const deps = pkg[field];
+        if (!deps)
+            continue;
+        out[field] = Object.fromEntries(Object.entries(deps).map(([dep, spec]) => [dep, dep.startsWith("@rivetjs/") || dep === "create-rivet" ? range : spec]));
+    }
+    return out;
+}
+/** Writes the project. Throws when the template is unknown. Does not install or run git. */
+export function createProject(options) {
+    const template = findTemplate(options.template);
+    if (!template)
+        throw new Error(`Unknown template "${options.template}" (${TEMPLATES.map((t) => t.id).join(", ")})`);
+    const source = join(options.templates ?? templatesRoot(), template.dir);
+    if (!existsSync(join(source, "package.json")))
+        throw new Error(`Template files missing: ${source}`);
+    const dir = resolve(options.dir);
+    const name = options.name ?? toPackageName(basename(dir));
+    mkdirSync(dir, { recursive: true });
+    const files = new Set(copyTemplateDir(source, dir));
+    let pkg = rewriteManifest(JSON.parse(readFileSync(join(dir, "package.json"), "utf8")), name, options.rivetVersion ?? versionRange(ownVersion()));
+    for (const overlay of options.overlays ?? []) {
+        if (overlay.dir)
+            for (const file of copyTemplateDir(overlay.dir, dir))
+                files.add(file);
+        if (overlay.manifest)
+            pkg = overlay.manifest(pkg);
+        const edited = overlay.edit?.(dir);
+        for (const file of edited?.written ?? [])
+            files.add(file);
+        for (const file of edited?.removed ?? [])
+            files.delete(file);
+    }
+    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;
+}
+/** `git init` + first commit, unless git is missing or `dir` is already inside a work tree. */
+export function initGit(dir) {
+    const git = (...args) => spawnSync("git", args, { cwd: dir, stdio: "pipe", encoding: "utf8" });
+    if (git("--version").status !== 0)
+        return "no-git";
+    if (git("rev-parse", "--is-inside-work-tree").stdout?.trim() === "true")
+        return "inside-repo";
+    if (git("init", "-q").status !== 0)
+        return "failed";
+    if (git("add", "-A").status !== 0)
+        return "failed";
+    // No identity configured: the repository stays initialised with the files staged.
+    return git("commit", "-q", "-m", "Initial commit from create-rivet").status === 0 ? "committed" : "created";
+}
+/** `dir` exists and is a file (not a folder). */
+export function isFile(path) {
+    return existsSync(path) && !statSync(path).isDirectory();
+}

package/main.d.ts

@@ -0,0 +1,9 @@
+import { type PromptIO } from "./prompt.js";
+export declare const HELP: string;
+export interface MainIO extends PromptIO {
+    error: NodeJS.WritableStream;
+    cwd: string;
+    env: Record<string, string | undefined>;
+}
+/** Runs the command; resolves with the exit code (0 ok, 1 error, 130 cancelled). */
+export declare function main(argv: string[], io: MainIO): Promise<number>;