create-runlot 0.1.0-rc.100

package/dist/index.js

@@ -0,0 +1,931 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { existsSync, mkdirSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { createInterface } from "node:readline/promises";
+var POSTS_MIGRATION = [
+  "-- Applied by `runlot deploy` (and by `runlot pg migrate`).",
+  "create table if not exists posts (",
+  "  id    serial primary key,",
+  "  owner text not null,",
+  "  title text not null",
+  ");",
+  "",
+  "-- One row so the example page has something to show before you write any.",
+  "insert into posts (owner, title)",
+  "select 'welcome', 'Your first post'",
+  "where not exists (select 1 from posts);",
+  ""
+].join("\n");
+var TEMPLATE_NAMES = ["next", "hono", "static", "studio"];
+function isTemplateName(v) {
+  return TEMPLATE_NAMES.includes(v);
+}
+var TEMPLATE_LIST = [
+  { name: "next", desc: "Next.js App Router \u2014 uses env.db and env.auth from server components" },
+  { name: "hono", desc: "Hono worker \u2014 REST API example (/posts, /upload)" },
+  { name: "static", desc: "A single static HTML page \u2014 assets only, no worker" },
+  // Last, so the numbers the other three answer to do not move.
+  { name: "studio", desc: "Vite + React + Tailwind and a Hono API \u2014 what runlot Studio builds" }
+];
+var USAGE = [
+  "create-runlot <dir> [--org <slug>] [--template next|hono|static|studio]",
+  "",
+  "  Creates a project from a Next.js, Hono, static-site, or studio template.",
+  "  Without --template, in a terminal, it asks which template to use.",
+  "  Then run: cd <dir> && runlot deploy"
+].join("\n");
+var NAME_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
+function pkgJson(obj) {
+  return JSON.stringify(obj, null, 2) + "\n";
+}
+var NEXT_TSCONFIG = pkgJson({
+  compilerOptions: {
+    lib: ["dom", "dom.iterable", "esnext"],
+    allowJs: true,
+    skipLibCheck: true,
+    strict: true,
+    noEmit: true,
+    esModuleInterop: true,
+    module: "esnext",
+    moduleResolution: "bundler",
+    resolveJsonModule: true,
+    isolatedModules: true,
+    jsx: "preserve",
+    incremental: true,
+    plugins: [{ name: "next" }]
+  },
+  include: ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  exclude: ["node_modules"]
+});
+var NEXT_CONFIG_TS = [
+  'import type { NextConfig } from "next";',
+  "",
+  "const config: NextConfig = {};",
+  "",
+  "export default config;",
+  ""
+].join("\n");
+function nextLayoutTsx(name) {
+  return [
+    'import type { Metadata } from "next";',
+    'import type { ReactNode } from "react";',
+    "",
+    "export const metadata: Metadata = {",
+    `  title: "${name}",`,
+    "};",
+    "",
+    "export default function RootLayout({ children }: { children: ReactNode }) {",
+    "  return (",
+    '<html lang="en">',
+    "      <body>{children}</body>",
+    "    </html>",
+    "  );",
+    "}",
+    ""
+  ].join("\n");
+}
+var NEXT_PAGE_TSX = [
+  'import { Pool } from "@runlot/pg";',
+  'import { env } from "@runlot/next";',
+  "",
+  "// `env` is request-scoped. Without this, Next prerenders this page during",
+  "// `next build`, where there is no request, and the build fails on the",
+  "// adapter's own error (field-notes #68).",
+  'export const dynamic = "force-dynamic";',
+  "",
+  "export default async function PostsPage() {",
+  "  const user = await env.auth.user();",
+  "  if (!user) {",
+  "    return (",
+  "      <p>",
+  '        Please sign in. <a href="/login">Sign in</a>',
+  "      </p>",
+  "    );",
+  "  }",
+  "",
+  "  const db = new Pool({ db: env.db });",
+  "",
+  // `query` defaults its row type to Record<string, unknown>. Without the type
+  // argument `p.id` and `p.title` are `unknown`, and `next build` — which type
+  // checks — fails before the bundler is ever reached.
+  "  const { rows } = await db.query<{ id: number; title: string }>(",
+  '    "select id, title from posts where owner = $1 limit 20",',
+  "    [user.id],",
+  "  );",
+  "",
+  "  return (",
+  "    <ul>",
+  "      {rows.map((p) => <li key={p.id}>{p.title}</li>)}",
+  "    </ul>",
+  "  );",
+  "}",
+  ""
+].join("\n");
+function nextReadme(name) {
+  return [
+    `# ${name}`,
+    "",
+    "A Next.js App Router template. `app/page.tsx` is a server component that lists",
+    "20 posts using `env.db` and `env.auth.user()`.",
+    "",
+    "```",
+    "runlot deploy",
+    "```",
+    "",
+    "Postgres, login and object storage come with the project \u2014 there is nothing to set up.",
+    "The App Router itself runs on workerd (OpenNext).",
+    "",
+    "`npm run dev` is `next dev` \u2014 the fast UI loop, without runlot's bindings.",
+    "`npm run preview` is `runlot dev`: it builds through OpenNext and serves the result",
+    "under workerd with the bindings wired up, which is where you check what will ship.",
+    ""
+  ].join("\n");
+}
+function nextTemplate(ctx) {
+  const { name, org } = ctx;
+  const runlotConfig = { name };
+  if (org) runlotConfig["org"] = org;
+  runlotConfig["framework"] = "next";
+  runlotConfig["assets"] = "public";
+  const packageJson = {
+    name,
+    version: "0.0.0",
+    private: true,
+    scripts: {
+      // `dev` stays `next dev`: for a Next project the UI loop is the thing you
+      // run all day, and `runlot dev` has to rebuild through OpenNext on every
+      // change. `preview` is the one that runs what will actually ship.
+      dev: "next dev",
+      preview: "runlot dev",
+      build: "next build",
+      start: "next start"
+    },
+    dependencies: {
+      next: "^16.3.4",
+      react: "^19.2.8",
+      "react-dom": "^19.2.8",
+      // The npm job in release.yml rewrites the version range with the same
+      // number as the tag — the value written here is the last published version.
+      "@runlot/next": "^0.1.0-rc.100",
+      "@runlot/pg": "^0.1.0-rc.100"
+    },
+    devDependencies: {
+      typescript: "^5.7.2",
+      "@types/react": "^19.2.18",
+      "@types/react-dom": "^19.2.5",
+      "@types/node": "^22.10.2"
+    }
+  };
+  return {
+    "package.json": pkgJson(packageJson),
+    "runlot.json": pkgJson(runlotConfig),
+    "tsconfig.json": NEXT_TSCONFIG,
+    "next.config.ts": NEXT_CONFIG_TS,
+    "app/layout.tsx": nextLayoutTsx(name),
+    "app/page.tsx": NEXT_PAGE_TSX,
+    "public/robots.txt": "User-agent: *\nAllow: /\n",
+    "migrations/0001_posts.sql": POSTS_MIGRATION,
+    // runlot deploy writes the generated OpenNext configuration into
+    // `.runlot-next` (docs/nextjs.md §2) — it is not source, so it is not
+    // something to commit.
+    ".gitignore": "node_modules\n.next\n.open-next\n.runlot-next\n.runlot\n.env.runlot\n",
+    "README.md": nextReadme(name)
+  };
+}
+var HONO_INDEX_TS = [
+  'import { Hono } from "hono";',
+  'import { Pool } from "@runlot/pg";',
+  'import type { Db, Storage } from "@runlot/pg";',
+  'import type { AuthBinding } from "@runlot/auth";',
+  "",
+  "// db, auth, and storage come with every runlot project.",
+  "interface Env {",
+  "  db: Db;",
+  "  auth: AuthBinding;",
+  "  storage: Storage;",
+  "  // public/ ships in the same bundle and is served through this.",
+  "  assets: { fetch(request: Request): Promise<Response> };",
+  "}",
+  "",
+  "const app = new Hono<{ Bindings: Env }>();",
+  "",
+  'app.get("/posts", async (c) => {',
+  "  const user = await c.env.auth.user(c.req.raw);",
+  "  // `user` is null until someone signs in, which is every first visit. The",
+  "  // landing sample leaves this out because it is for display; a project that",
+  "  // runs cannot (field-notes #69).",
+  "  if (!user) {",
+  '    return c.json({ error: "sign in at /__runlot/auth/sign-in" }, 401);',
+  "  }",
+  "",
+  "  const db = new Pool({ db: c.env.db });",
+  "",
+  "  const { rows } = await db.query(",
+  '    "select id, title from posts where owner = $1 limit 20",',
+  "    [user.id],",
+  "  );",
+  "  return c.json(rows);",
+  "});",
+  "",
+  'app.post("/upload", async (c) => {',
+  "  const form = await c.req.formData();",
+  '  const file = form.get("file") as File;',
+  '  const url = await c.env.storage.put("covers/" + file.name, file);',
+  "  return c.json({ url });",
+  "});",
+  "",
+  "// With `main` set, the worker is the entry point and static files are not",
+  "// served ahead of it \u2014 so whatever the routes above did not answer is handed",
+  "// to the assets binding. Without this line public/hello.txt is a 404, which",
+  "// is what the template shipped until field-notes #71.",
+  'app.all("*", (c) => c.env.assets.fetch(c.req.raw));',
+  "",
+  "export default app;",
+  ""
+].join("\n");
+function honoReadme(name) {
+  return [
+    `# ${name}`,
+    "",
+    "A Hono worker template. `src/index.ts` has two routes: `/posts` (a list) and",
+    "`/upload` (an object storage upload).",
+    "",
+    "```",
+    "runlot dev",
+    "runlot deploy",
+    "```",
+    "",
+    "`runlot dev` runs this worker on your own machine under workerd, with `env.storage`",
+    "and the static files real and `env.db` and `env.auth` as local stand-ins. It prints",
+    "which is which. Point `env.db` at a real database with `RUNLOT_DEV_DATABASE_URL`.",
+    "",
+    "`db`, `auth` and `storage` on `Env` come with the project \u2014 there is nothing to set up.",
+    ""
+  ].join("\n");
+}
+function honoTemplate(ctx) {
+  const { name, org } = ctx;
+  const runlotConfig = { name };
+  if (org) runlotConfig["org"] = org;
+  runlotConfig["main"] = "src/index.ts";
+  runlotConfig["assets"] = "public";
+  const packageJson = {
+    name,
+    version: "0.0.0",
+    private: true,
+    type: "module",
+    // `npm run dev` is the first thing a person types in a new directory, and
+    // for this template it should be the local run — not a deploy.
+    scripts: {
+      dev: "runlot dev",
+      deploy: "runlot deploy"
+    },
+    dependencies: {
+      hono: "^4.10.7",
+      "@runlot/pg": "^0.1.0-rc.100",
+      "@runlot/auth": "^0.1.0-rc.100"
+    },
+    devDependencies: {
+      typescript: "^5.7.2",
+      "@types/node": "^22.10.2"
+    }
+  };
+  const tsconfig = pkgJson({
+    compilerOptions: {
+      target: "ES2022",
+      lib: ["ES2022", "DOM"],
+      module: "ESNext",
+      moduleResolution: "bundler",
+      strict: true,
+      skipLibCheck: true,
+      noEmit: true
+    },
+    include: ["src"]
+  });
+  return {
+    "package.json": pkgJson(packageJson),
+    "runlot.json": pkgJson(runlotConfig),
+    "tsconfig.json": tsconfig,
+    "src/index.ts": HONO_INDEX_TS,
+    "public/hello.txt": "Static assets ship in the same bundle.\n",
+    "migrations/0001_posts.sql": POSTS_MIGRATION,
+    // `.runlot` is where `runlot dev` keeps the unpacked bundle, the local
+    // object store and the mail it did not send.
+    ".gitignore": "node_modules\n.runlot\n.env.runlot\n",
+    "README.md": honoReadme(name)
+  };
+}
+function staticIndexHtml(name) {
+  return [
+    "<!doctype html>",
+    '<html lang="en">',
+    "  <head>",
+    '    <meta charset="utf-8" />',
+    '    <meta name="viewport" content="width=device-width, initial-scale=1" />',
+    `    <title>${name}</title>`,
+    "  </head>",
+    "  <body>",
+    "    <main>",
+    `      <h1>${name}</h1>`,
+    "      <p>",
+    "        This page is deployed as a static asset. Edit the files under <code>public/</code>",
+    "        and run <code>runlot deploy</code> to publish the change.",
+    "      </p>",
+    "    </main>",
+    "  </body>",
+    "</html>",
+    ""
+  ].join("\n");
+}
+function staticReadme(name) {
+  return [
+    `# ${name}`,
+    "",
+    "A static site template. It is a single `public/index.html` with no worker.",
+    "",
+    "```",
+    "runlot dev",
+    "runlot deploy",
+    "```",
+    "",
+    "`runlot dev` serves `public/` the way the deployment will, including the `notFound`",
+    "setting, and reloads when you save.",
+    "",
+    'The project already has a database, login and storage. Add a worker (`"main"` in',
+    "`runlot.json`) when you want to use them \u2014 `env.db`, `env.auth` and `env.storage` are there.",
+    ""
+  ].join("\n");
+}
+function staticTemplate(ctx) {
+  const { name, org } = ctx;
+  const runlotConfig = { name };
+  if (org) runlotConfig["org"] = org;
+  runlotConfig["assets"] = "public";
+  return {
+    // If you use client-side routing (React Router and so on), add
+    // `"notFound": "spa"` — extensionless paths then answer with index.html.
+    "runlot.json": pkgJson(runlotConfig),
+    "public/index.html": staticIndexHtml(name),
+    ".gitignore": "node_modules\n.runlot\n",
+    "README.md": staticReadme(name)
+  };
+}
+var STUDIO_MIGRATION = [
+  "-- Applied by `runlot deploy` (and by `runlot pg migrate`).",
+  "--",
+  "-- Forward only. An applied migration is compared by content hash on the next run",
+  "-- (`Migration changed after it was applied`), so change the schema by adding",
+  "-- 0002_*.sql rather than by editing this file.",
+  "create table if not exists notes (",
+  "  id         serial primary key,",
+  "  owner      text not null,",
+  "  title      text not null,",
+  "  created_at timestamptz not null default now()",
+  ");",
+  "",
+  "-- The list is per signed-in user, newest first.",
+  "create index if not exists notes_owner_id on notes (owner, id desc);",
+  ""
+].join("\n");
+var STUDIO_SEED = [
+  "-- Development data only. It is applied by `runlot dev`, never by `runlot deploy`.",
+  "insert into notes (owner, title)",
+  "select 'dev', '\uCCAB \uBA54\uBAA8\uC785\uB2C8\uB2E4'",
+  "where not exists (select 1 from notes);",
+  ""
+].join("\n");
+function studioIndexHtml(name) {
+  return [
+    "<!doctype html>",
+    '<html lang="ko">',
+    "  <head>",
+    '    <meta charset="utf-8" />',
+    '    <meta name="viewport" content="width=device-width, initial-scale=1" />',
+    `    <title>${name}</title>`,
+    "  </head>",
+    "  <body>",
+    '    <div id="root"></div>',
+    '    <script type="module" src="/src/main.tsx"></script>',
+    "  </body>",
+    "</html>",
+    ""
+  ].join("\n");
+}
+var STUDIO_VITE_CONFIG = [
+  'import tailwindcss from "@tailwindcss/vite";',
+  'import react from "@vitejs/plugin-react";',
+  'import { defineConfig } from "vite";',
+  "",
+  "export default defineConfig({",
+  "  plugins: [react(), tailwindcss()],",
+  '  // `runlot.json` points "assets" at this directory, and `runlot deploy` ships it as',
+  "  // it stands on disk \u2014 it does not build it. That is why `npm run deploy` is two",
+  "  // commands.",
+  '  build: { outDir: "assets", emptyOutDir: true },',
+  "  server: {",
+  "    // /api belongs to the worker. `npm run dev:api` runs it under workerd on 8787,",
+  "    // with env.db, env.auth and env.storage wired up.",
+  '    proxy: { "/api": "http://127.0.0.1:8787" },',
+  "  },",
+  "});",
+  ""
+].join("\n");
+var STUDIO_MAIN_TSX = [
+  'import { createRoot } from "react-dom/client";',
+  'import { App } from "./App";',
+  'import "./styles.css";',
+  "",
+  "// This module exports no component, so editing it is a full reload rather than a",
+  "// Fast Refresh. That is Vite's rule, and it is why App.tsx holds the component.",
+  'const root = document.getElementById("root");',
+  'if (!root) throw new Error("#root is missing in index.html");',
+  "createRoot(root).render(<App />);",
+  ""
+].join("\n");
+var STUDIO_STYLES_CSS = [
+  '@import "tailwindcss";',
+  ""
+].join("\n");
+var STUDIO_API_TS = [
+  "// The worker's answers, typed, and the two calls the page makes.",
+  "//",
+  "// The paths are relative. The same bundle is served on the dev port, on a Studio",
+  "// preview, on a share link and on the project's own hostname, so a hard-coded",
+  "// origin would be wrong on three of the four.",
+  "export interface Note {",
+  "  id: number;",
+  "  title: string;",
+  "}",
+  "",
+  "export interface NotesView {",
+  "  signedIn: boolean;",
+  "  notes: Note[];",
+  "}",
+  "",
+  "export async function listNotes(): Promise<NotesView> {",
+  '  const res = await fetch("/api/notes");',
+  "  // env.auth.user() answers null until someone signs in, which is every first",
+  "  // visit \u2014 not an error.",
+  "  if (res.status === 401) return { signedIn: false, notes: [] };",
+  "  if (!res.ok) throw new Error(`GET /api/notes: ${res.status}`);",
+  "  return { signedIn: true, notes: (await res.json()) as Note[] };",
+  "}",
+  "",
+  "export async function addNote(title: string): Promise<void> {",
+  '  const res = await fetch("/api/notes", {',
+  '    method: "POST",',
+  '    headers: { "Content-Type": "application/json" },',
+  "    body: JSON.stringify({ title }),",
+  "  });",
+  "  if (!res.ok) throw new Error(`POST /api/notes: ${res.status}`);",
+  "}",
+  ""
+].join("\n");
+var STUDIO_APP_TSX = [
+  'import { useEffect, useState } from "react";',
+  'import { addNote, listNotes, type Note } from "./api";',
+  "",
+  "export function App() {",
+  "  const [notes, setNotes] = useState<Note[]>([]);",
+  "  const [signedIn, setSignedIn] = useState(true);",
+  '  const [title, setTitle] = useState("");',
+  "  const [error, setError] = useState<string | null>(null);",
+  "",
+  "  function reload(): void {",
+  "    listNotes()",
+  "      .then((v) => {",
+  "        setSignedIn(v.signedIn);",
+  "        setNotes(v.notes);",
+  "        setError(null);",
+  "      })",
+  "      .catch((e: unknown) => setError(String(e)));",
+  "  }",
+  "",
+  "  useEffect(reload, []);",
+  "",
+  "  return (",
+  '    <main className="mx-auto max-w-md p-8">',
+  '      <h1 className="text-2xl font-semibold">\uBA54\uBAA8</h1>',
+  "",
+  "      {!signedIn && (",
+  '        <p className="mt-4 text-sm">',
+  '          <a className="underline" href="/__runlot/auth/sign-in">',
+  "            \uB85C\uADF8\uC778\uD569\uB2C8\uB2E4",
+  "          </a>",
+  "        </p>",
+  "      )}",
+  "",
+  '      {error && <p className="mt-4 text-sm text-red-600">{error}</p>}',
+  "",
+  "      <form",
+  '        className="mt-4 flex gap-2"',
+  "        onSubmit={(e) => {",
+  "          e.preventDefault();",
+  "          if (!title.trim()) return;",
+  "          addNote(title)",
+  "            .then(() => {",
+  '              setTitle("");',
+  "              reload();",
+  "            })",
+  "            .catch((err: unknown) => setError(String(err)));",
+  "        }}",
+  "      >",
+  "        <input",
+  '          className="flex-1 rounded border px-2 py-1"',
+  '          placeholder="\uBB34\uC5C7\uC744 \uC801\uC744\uAE4C\uC694?"',
+  "          value={title}",
+  "          onChange={(e) => setTitle(e.target.value)}",
+  "        />",
+  '        <button className="rounded bg-black px-3 py-1 text-white" type="submit">',
+  "          \uCD94\uAC00",
+  "        </button>",
+  "      </form>",
+  "",
+  '      <ul className="mt-6 space-y-1">',
+  "        {notes.map((n) => (",
+  "          <li key={n.id}>{n.title}</li>",
+  "        ))}",
+  "      </ul>",
+  "",
+  '      {signedIn && notes.length === 0 && <p className="mt-6 text-sm">\uC544\uC9C1 \uBA54\uBAA8\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4.</p>}',
+  "    </main>",
+  "  );",
+  "}",
+  ""
+].join("\n");
+var STUDIO_WORKER_TS = [
+  'import type { AuthBinding } from "@runlot/auth";',
+  'import { Pool } from "@runlot/pg";',
+  'import type { Db, Storage } from "@runlot/pg";',
+  'import { Hono } from "hono";',
+  "",
+  "// Declared in runlot.json; `runlot deploy` creates each one and binds it here.",
+  "interface Env {",
+  "  db: Db;",
+  "  auth: AuthBinding;",
+  "  storage: Storage;",
+  "  // The Vite build output. It ships in the same bundle as this worker.",
+  "  assets: { fetch(request: Request): Promise<Response> };",
+  "}",
+  "",
+  "const app = new Hono<{ Bindings: Env }>();",
+  "",
+  'app.get("/api/notes", async (c) => {',
+  "  const user = await c.env.auth.user(c.req.raw);",
+  "  // null until someone signs in, which is every first visit.",
+  '  if (!user) return c.json({ error: "sign in at /__runlot/auth/sign-in" }, 401);',
+  "",
+  "  const db = new Pool({ db: c.env.db });",
+  "  const { rows } = await db.query<{ id: number; title: string }>(",
+  '    "select id, title from notes where owner = $1 order by id desc limit 50",',
+  "    [user.id],",
+  "  );",
+  "  return c.json(rows);",
+  "});",
+  "",
+  'app.post("/api/notes", async (c) => {',
+  "  const user = await c.env.auth.user(c.req.raw);",
+  '  if (!user) return c.json({ error: "sign in at /__runlot/auth/sign-in" }, 401);',
+  "",
+  "  const body = (await c.req.json()) as { title?: string };",
+  "  const title = body.title?.trim();",
+  '  if (!title) return c.json({ error: "title is required" }, 400);',
+  "",
+  "  const db = new Pool({ db: c.env.db });",
+  "  // One statement per request. The node's ceiling is 10 s and a tenant cannot",
+  "  // raise it, so work that takes longer belongs in a cron, not in a request.",
+  '  await db.query("insert into notes (owner, title) values ($1, $2)", [user.id, title]);',
+  "  return c.json({ ok: true }, 201);",
+  "});",
+  "",
+  'app.get("/api/me", async (c) => {',
+  "  const user = await c.env.auth.user(c.req.raw);",
+  "  // The origin is read out of the request, never written as a constant: this same",
+  "  // bundle answers on the dev port, on a Studio preview, on a share link and on the",
+  "  // project's own hostname (docs/studio.md \xA76.8).",
+  '  const signIn = new URL("/__runlot/auth/sign-in", c.req.url).toString();',
+  "  return c.json({ id: user?.id ?? null, signIn });",
+  "});",
+  "",
+  "// With `main` set the worker is the entry point and static files are not served",
+  "// ahead of it, so whatever the routes above did not answer is handed to the assets",
+  "// binding here. Without this line every file in assets/ is a 404",
+  "// (docs/field-notes.md #71).",
+  'app.all("*", (c) => c.env.assets.fetch(c.req.raw));',
+  "",
+  "export default app;",
+  ""
+].join("\n");
+function studioAgents(name) {
+  return [
+    `# ${name}`,
+    "",
+    "This project runs on Runlot. Read this before changing code: the platform refuses a",
+    "few things Node and Next allow, and the refusals are not visible in the type system.",
+    "",
+    "## What is bound",
+    "",
+    "| Binding | Declared in `runlot.json` | Used as |",
+    "|---|---|---|",
+    '| `env.db` | `"database": true` | `new Pool({ db: c.env.db })` \u2014 Postgres |',
+    '| `env.auth` | `"auth": true` | `c.env.auth.user(c.req.raw)` \u2014 **null** until someone signs in |',
+    '| `env.storage` | `"storage": true` | `c.env.storage.put(key, file)` |',
+    '| `env.assets` | `"assets": "assets"` | the Vite build output, served by the catch-all route |',
+    "",
+    '`env.ai` is deliberately **not** declared. Add `"ai": true` in the same change that',
+    "first calls it, and say so in that turn: it is metered.",
+    "",
+    "## Layout",
+    "",
+    "- `src/` \u2014 Vite + React + Tailwind. `npm run build` writes it into `assets/`.",
+    "- `worker/index.ts` \u2014 one Hono worker. Every API path is under `/api`.",
+    "- `migrations/NNNN_*.sql` \u2014 the schema, forward only. `seed.sql` is development data.",
+    "",
+    "## Refusals",
+    "",
+    "- **No `node:fs`, and `nodejs_compat` is not a single switch.** Importing a node",
+    "  built-in requires the flag, which the deploy turns on when it sees the import \u2014 but",
+    "  *which* built-ins that flag hands out is decided by `compatibilityDate`, not by the",
+    "  build. Prefer Web APIs (`fetch`, `URL`, `crypto`, `TextEncoder`); there is no file",
+    "  system at any date.",
+    "- **No long-running process.** A request ends when its response does. Recurring work",
+    '  is a cron (`"triggers": { "crons": [...] }`) or a queue \u2014 never a `setInterval`.',
+    "- **10 s per statement.** The node enforces the ceiling and a tenant cannot raise it;",
+    "  a slower statement ends in `57014`. Split the query or move it to a cron.",
+    "- **No install scripts.** A dependency's `postinstall` does not run \u2014 Studio installs",
+    "  packages itself, and nothing at deploy time runs one either. A package that needs",
+    "  one to place a native binary does not work here.",
+    '- **Build absolute URLs out of the request.** `new URL("/path", request.url)`, never a',
+    "  hard-coded origin. The same bundle answers on the dev port, on a Studio preview, on",
+    "  a share link and on the project's own hostname, and a constant is wrong on three of",
+    "  those four.",
+    "- **`runWorkerFirst` is on.** The worker sees every request, so the catch-all",
+    '  `app.all("*", \u2026)` at the bottom of `worker/index.ts` is what serves `assets/`.',
+    "  Delete it and every static file is a 404.",
+    "",
+    "## Hot reload",
+    "",
+    "The dev loop is Vite's, so the idiom is Vite's: `import.meta.hot`. What survives an",
+    "edit depends on what the module exports.",
+    "",
+    "- **A module that exports only components hot-swaps and keeps state.** `src/App.tsx`",
+    "  is one. Keep it that way \u2014 a half-filled form surviving an edit is the whole point.",
+    "- Anything that is not a component (types, constants, helpers) goes in its own file,",
+    "  like `src/api.ts`. Exporting one alongside a component downgrades that module to a",
+    "  reload.",
+    "- `worker/` rebuilds by itself: the page stays and the next `/api` call reaches the",
+    "  new code. A change to `migrations/` or `package.json` is a full reload.",
+    "",
+    "## Commands",
+    "",
+    "```",
+    "npm install",
+    "npm run dev       # the UI on :5173, with /api proxied to the worker",
+    "npm run dev:api   # the worker under workerd with the bindings (second terminal)",
+    "npm run deploy    # vite build, then runlot deploy",
+    "```",
+    "",
+    "`runlot deploy` ships `assets/` as it stands on disk and does not build it. That is",
+    "why `deploy` is two commands, and why `assets/` is in `.gitignore`.",
+    ""
+  ].join("\n");
+}
+function studioReadme(name) {
+  return [
+    `# ${name}`,
+    "",
+    "Vite + React + Tailwind in `src/`, one Hono worker in `worker/index.ts`, and",
+    "Postgres, login and object storage declared in `runlot.json`.",
+    "",
+    "```",
+    "npm install",
+    "npm run dev:api   # the worker under workerd, with env.db, env.auth, env.storage",
+    "npm run dev       # the UI, with /api proxied to it",
+    "npm run deploy    # vite build, then runlot deploy",
+    "```",
+    "",
+    "`npm run deploy` is two commands because `runlot deploy` ships `assets/` as it",
+    "stands on disk: the Vite build has to run first.",
+    "",
+    "`AGENTS.md` states the bindings and what the platform refuses. `CLAUDE.md` is the",
+    "same file under the name Claude Code reads.",
+    ""
+  ].join("\n");
+}
+function studioTemplate(ctx) {
+  const { name, org } = ctx;
+  const runlotConfig = { name };
+  if (org) runlotConfig["org"] = org;
+  runlotConfig["main"] = "worker/index.ts";
+  runlotConfig["assets"] = "assets";
+  runlotConfig["notFound"] = "spa";
+  runlotConfig["runWorkerFirst"] = true;
+  runlotConfig["database"] = true;
+  runlotConfig["auth"] = true;
+  runlotConfig["storage"] = true;
+  const packageJson = {
+    name,
+    version: "0.0.0",
+    private: true,
+    type: "module",
+    scripts: {
+      dev: "vite",
+      "dev:api": "runlot dev",
+      build: "vite build",
+      // `runlot deploy` does not build. Without the build in front of it, the deploy
+      // ships whatever `assets/` last held — or fails because it is not there.
+      deploy: "npm run build && runlot deploy",
+      typecheck: "tsc --noEmit"
+    },
+    dependencies: {
+      hono: "^4.10.7",
+      react: "^19.2.8",
+      "react-dom": "^19.2.8",
+      // The npm job in release.yml rewrites these ranges with the same number as the
+      // tag — what is written here is the last published version.
+      "@runlot/pg": "^0.1.0-rc.100",
+      "@runlot/auth": "^0.1.0-rc.100"
+    },
+    devDependencies: {
+      "@tailwindcss/vite": "^4.3.3",
+      "@types/react": "^19.2.18",
+      "@types/react-dom": "^19.2.5",
+      "@vitejs/plugin-react": "^6.1.1",
+      tailwindcss: "^4.3.3",
+      typescript: "^5.7.2",
+      vite: "^8.2.2"
+    }
+  };
+  const tsconfig = pkgJson({
+    compilerOptions: {
+      target: "ES2022",
+      lib: ["ES2022", "DOM", "DOM.Iterable"],
+      module: "ESNext",
+      moduleResolution: "bundler",
+      jsx: "react-jsx",
+      strict: true,
+      skipLibCheck: true,
+      noEmit: true,
+      // `import.meta.hot` and `import.meta.env` are typed by this and nothing else.
+      types: ["vite/client"]
+    },
+    include: ["src", "worker", "vite.config.ts"]
+  });
+  const agents = studioAgents(name);
+  return {
+    "package.json": pkgJson(packageJson),
+    "runlot.json": pkgJson(runlotConfig),
+    "tsconfig.json": tsconfig,
+    "vite.config.ts": STUDIO_VITE_CONFIG,
+    "index.html": studioIndexHtml(name),
+    "src/main.tsx": STUDIO_MAIN_TSX,
+    "src/App.tsx": STUDIO_APP_TSX,
+    "src/api.ts": STUDIO_API_TS,
+    "src/styles.css": STUDIO_STYLES_CSS,
+    "worker/index.ts": STUDIO_WORKER_TS,
+    "migrations/0001_init.sql": STUDIO_MIGRATION,
+    "seed.sql": STUDIO_SEED,
+    // Both names, one text. Claude Code reads CLAUDE.md and other agents read
+    // AGENTS.md; generating them together is what keeps them saying the same thing.
+    "AGENTS.md": agents,
+    "CLAUDE.md": `<!-- The same text as AGENTS.md. Change both, or the two agents disagree. -->
+${agents}`,
+    // `assets/` is build output. `.runlot` holds the unpacked bundle and the local
+    // object store, and `.env.runlot` holds secrets.
+    ".gitignore": "node_modules\nassets\n.runlot\n.env.runlot\n",
+    "README.md": studioReadme(name)
+  };
+}
+var TEMPLATES = {
+  next: nextTemplate,
+  hono: honoTemplate,
+  static: staticTemplate,
+  studio: studioTemplate
+};
+function templateFiles(template, ctx = {}) {
+  if (!isTemplateName(template)) {
+    throw new Error(`"${template}" is not a template. Use one of: ${TEMPLATE_NAMES.join(", ")}.`);
+  }
+  return TEMPLATES[template]({ name: ctx.name ?? "app", org: ctx.org });
+}
+function scaffold(opts) {
+  const { target, org, template } = opts;
+  const dir = resolve(target);
+  const name = target.split("/").filter(Boolean).pop();
+  if (!NAME_RE.test(name)) {
+    throw new Error(`"${name}" cannot be used as a project name. Use lowercase letters, digits, and hyphens.`);
+  }
+  if (existsSync(dir)) throw new Error(`${dir} already exists. Choose another name, or remove that directory and run this again.`);
+  const files = TEMPLATES[template]({ name, org });
+  const relPaths = Object.keys(files).sort();
+  for (const rel of relPaths) {
+    const path = join(dir, rel);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, files[rel]);
+  }
+  console.log(`Created ${dir}.`);
+  console.log(`  cd ${target}`);
+  if (template === "studio") {
+    console.log("  npm install");
+    console.log("  npm run dev:api   # a second terminal: the worker with the bindings");
+    console.log("  npm run dev");
+    console.log(org ? "  npm run deploy" : "  npm run deploy -- --org <slug>");
+  } else {
+    if (template !== "next") console.log("  runlot dev");
+    console.log(org ? "  runlot deploy" : "  runlot deploy --org <slug>");
+  }
+  return { dir, files: relPaths };
+}
+async function defaultAsk(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await rl.question(question);
+  } finally {
+    rl.close();
+  }
+}
+var MAX_PROMPT_TRIES = 3;
+async function chooseTemplate(ask) {
+  const listText = TEMPLATE_LIST.map((t, i) => `  ${i + 1}. ${t.name.padEnd(6)} ${t.desc}`).join("\n");
+  const question = `Which template do you want?
+
+${listText}
+
+Enter a name or a number: `;
+  for (let attempt = 1; attempt <= MAX_PROMPT_TRIES; attempt++) {
+    const answer = (await ask(question)).trim();
+    const byIndex = TEMPLATE_LIST[Number(answer) - 1];
+    const byName = TEMPLATE_LIST.find((t) => t.name === answer);
+    const picked = byIndex ?? byName;
+    if (picked) return picked.name;
+    console.error(`Unknown answer: "${answer}". Choose one of ${TEMPLATE_NAMES.join(", ")}.`);
+  }
+  throw new Error(`No template chosen after ${MAX_PROMPT_TRIES} tries. Specify one with --template.`);
+}
+async function run(argv, deps) {
+  const args = [];
+  let org;
+  let templateArg;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--org") {
+      org = argv[++i];
+      if (org === void 0) throw new Error("--org requires a value");
+    } else if (a === "--template") {
+      templateArg = argv[++i];
+      if (templateArg === void 0) throw new Error("--template requires a value");
+    } else if (a === "-h" || a === "--help") {
+      console.log(USAGE);
+      return 0;
+    } else {
+      args.push(a);
+    }
+  }
+  const target = args[0];
+  if (!target) {
+    console.error(USAGE);
+    return 2;
+  }
+  let template;
+  if (templateArg !== void 0) {
+    if (!isTemplateName(templateArg)) {
+      throw new Error(`Unknown template: "${templateArg}". Choose one of ${TEMPLATE_NAMES.join(", ")}.`);
+    }
+    template = templateArg;
+  } else if (deps.isTTY ?? process.stdin.isTTY === true) {
+    template = await chooseTemplate(deps.ask ?? defaultAsk);
+  } else {
+    throw new Error(`--template is required. Choose one of ${TEMPLATE_NAMES.join(", ")}.`);
+  }
+  scaffold({ target, org, template });
+  return 0;
+}
+async function main(argv, deps = {}) {
+  try {
+    return await run(argv, deps);
+  } catch (err) {
+    console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}
+function runDirectly(argv1) {
+  if (!argv1) return false;
+  let path = argv1;
+  try {
+    path = realpathSync(argv1);
+  } catch {
+  }
+  return path.endsWith(`${sep}dist${sep}index.js`);
+}
+if (runDirectly(process.argv[1])) {
+  main(process.argv.slice(2)).then((code) => process.exit(code));
+}
+export {
+  TEMPLATE_NAMES,
+  main,
+  runDirectly,
+  scaffold,
+  templateFiles
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "create-runlot",
+  "version": "0.1.0-rc.100",
+  "description": "npm create runlot — Next.js, Hono, and static-site templates",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/runlot/runlot",
+    "directory": "web/apps/create-runlot"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "bin": {
+    "create-runlot": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "esbuild": "^0.24.2",
+    "typescript": "^5.7.2",
+    "@types/node": "^22.10.2",
+    "@runlot/config": "0.1.0-rc.100"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js --banner:js='#!/usr/bin/env node'",
+    "test": "node build.mjs",
+    "typecheck": "tsc --noEmit"
+  }
+}