create-runlot 0.1.0-rc.95 → 0.1.0-rc.97

package/dist/index.js

@@ -18,19 +18,21 @@ var POSTS_MIGRATION = [
   "where not exists (select 1 from posts);",
   ""
 ].join("\n");
-var TEMPLATE_NAMES = ["next", "hono", "static"];
+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" }
+  { 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]",
+  "create-runlot <dir> [--org <slug>] [--template next|hono|static|studio]",
   "",
-  "  Creates a project from a Next.js, Hono, or static-site template.",
+  "  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");
@@ -170,8 +172,8 @@ function nextTemplate(ctx) {
       "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.95",
-      "@runlot/pg": "^0.1.0-rc.95"
+      "@runlot/next": "^0.1.0-rc.97",
+      "@runlot/pg": "^0.1.0-rc.97"
     },
     devDependencies: {
       typescript: "^5.7.2",
@@ -290,8 +292,8 @@ function honoTemplate(ctx) {
     },
     dependencies: {
       hono: "^4.10.7",
-      "@runlot/pg": "^0.1.0-rc.95",
-      "@runlot/auth": "^0.1.0-rc.95"
+      "@runlot/pg": "^0.1.0-rc.97",
+      "@runlot/auth": "^0.1.0-rc.97"
     },
     devDependencies: {
       typescript: "^5.7.2",
@@ -378,11 +380,444 @@ function staticTemplate(ctx) {
     "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.97",
+      "@runlot/auth": "^0.1.0-rc.97"
+    },
+    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
+  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);
@@ -400,8 +835,15 @@ function scaffold(opts) {
   }
   console.log(`Created ${dir}.`);
   console.log(`  cd ${target}`);
-  if (template !== "next") console.log("  runlot dev");
-  console.log(org ? "  runlot deploy" : "  runlot deploy --org <slug>");
+  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) {
@@ -489,7 +931,9 @@ if (runDirectly(process.argv[1])) {
   main(process.argv.slice(2)).then((code) => process.exit(code));
 }
 export {
+  TEMPLATE_NAMES,
   main,
   runDirectly,
-  scaffold
+  scaffold,
+  templateFiles
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-runlot",
-  "version": "0.1.0-rc.95",
+  "version": "0.1.0-rc.97",
   "description": "npm create runlot — Next.js, Hono, and static-site templates",
   "publishConfig": {
     "access": "public"
@@ -11,6 +11,9 @@
     "directory": "web/apps/create-runlot"
   },
   "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  },
   "bin": {
     "create-runlot": "./dist/index.js"
   },
@@ -21,7 +24,7 @@
     "esbuild": "^0.24.2",
     "typescript": "^5.7.2",
     "@types/node": "^22.10.2",
-    "@runlot/config": "0.1.0-rc.95"
+    "@runlot/config": "0.1.0-rc.97"
   },
   "engines": {
     "node": ">=20"