@shaferllc/keel 0.82.0 → 0.83.0

package/templates/app/app/Controllers/HomeController.ts

@@ -0,0 +1,10 @@
+import type { Ctx } from "@shaferllc/keel/core";
+import { auth, view } from "@shaferllc/keel/core";
+
+import Welcome from "../../resources/views/welcome.js";
+
+export class HomeController {
+  async index(c: Ctx) {
+    return c.html(await view(Welcome, { signedIn: auth().check() }));
+  }
+}

package/templates/app/app/Http/Kernel.ts

@@ -0,0 +1,21 @@
+import { HttpKernel, serveStatic, sessionMiddleware } from "@shaferllc/keel/core";
+import type { Application } from "@shaferllc/keel/core";
+
+import { requestLogger } from "./Middleware/requestLogger.js";
+
+/**
+ * Global middleware — runs on every request, in order.
+ *
+ * Keel's own `serveStatic` (not `@hono/node-server`'s) because this kernel also runs
+ * inside the Worker: it imports `node:fs` dynamically, so it loads on the edge.
+ * Files resolve as `root + path` — /assets/app.css is ./public/assets/app.css.
+ */
+export class Kernel extends HttpKernel {
+  constructor(app: Application) {
+    super(app);
+
+    this.use(requestLogger);
+    this.use(serveStatic({ root: "./public" }));
+    this.use(sessionMiddleware());
+  }
+}

package/templates/app/app/Http/Middleware/requestLogger.ts

@@ -0,0 +1,8 @@
+import type { Ctx } from "@shaferllc/keel/core";
+
+/** Log every request with its status and how long it took. */
+export async function requestLogger(c: Ctx, next: () => Promise<void>): Promise<void> {
+  const started = Date.now();
+  await next();
+  console.log(`${c.req.method} ${c.req.path} ${c.res.status} ${Date.now() - started}ms`);
+}

package/templates/app/app/Models/User.ts

@@ -0,0 +1,15 @@
+import { Model } from "@shaferllc/keel/core";
+
+export class User extends Model {
+  static override table = "users";
+  static override fillable = ["name", "email", "password"];
+  // Never serialize these — `hidden` is a denylist on toJSON().
+  static override hidden = ["password", "two_factor_secret", "two_factor_recovery_codes"];
+  static override timestamps = true;
+
+  declare id: number;
+  declare name: string;
+  declare email: string;
+  declare password: string;
+  declare email_verified_at: string | null;
+}

package/templates/app/app/Providers/AppServiceProvider.ts

@@ -0,0 +1,12 @@
+import { ServiceProvider, setUserProvider } from "@shaferllc/keel/core";
+
+import { User } from "../Models/User.js";
+
+export class AppServiceProvider extends ServiceProvider {
+  register(): void {}
+
+  boot(): void {
+    // How `auth().user()` loads the signed-in user from the id in the session.
+    setUserProvider((id) => User.find(Number(id)));
+  }
+}

package/templates/app/app/Providers/DatabaseServiceProvider.ts

@@ -0,0 +1,52 @@
+import { ServiceProvider, config, setConnection } from "@shaferllc/keel/core";
+
+/**
+ * Opens the connection every model and query builder reads through — on **Node**.
+ * (In the Worker, worker.ts binds D1 directly and this provider isn't loaded.)
+ *
+ * Switching database is `DB_CONNECTION` and nothing else: no model or query changes,
+ * because they all talk to a `Connection` rather than to a driver.
+ *
+ * `d1` here means the HTTP API rather than the binding — which is what lets
+ * `keel migrate` reach your real D1 database from your laptop and from CI, where no
+ * binding exists.
+ */
+export class DatabaseServiceProvider extends ServiceProvider {
+  async register(): Promise<void> {
+    const name = config<string>("database.default", "sqlite");
+
+    if (name === "d1") {
+      const { d1HttpConnection } = await import("@shaferllc/keel/db/d1-http");
+
+      setConnection(
+        d1HttpConnection({
+          accountId: config<string>("database.connections.d1.accountId", ""),
+          databaseId: config<string>("database.connections.d1.databaseId", ""),
+          apiToken: config<string>("database.connections.d1.apiToken", ""),
+        }),
+        "sqlite",
+      );
+      return;
+    }
+
+    if (name === "postgres") {
+      const { pgConnection } = await import("@shaferllc/keel/db/pg");
+      const { Pool } = await import("pg");
+
+      setConnection(
+        pgConnection(new Pool({ connectionString: config<string>("database.connections.postgres.url", "") })),
+        "postgres",
+      );
+      return;
+    }
+
+    // sqlite (a local file) or turso (libSQL over the network) — same driver.
+    const { libsqlConnection } = await import("@shaferllc/keel/db/libsql");
+    const { createClient } = await import("@libsql/client");
+
+    const url = config<string>(`database.connections.${name}.url`, "file:./database.sqlite");
+    const authToken = config<string>(`database.connections.${name}.authToken`, "");
+
+    setConnection(libsqlConnection(createClient(authToken ? { url, authToken } : { url })), "sqlite");
+  }
+}

package/templates/app/bin/keel.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env tsx
+/**
+ * The application console. `npm run keel <command>`.
+ *
+ * The commands — serve, routes, repl, migrate:*, every make:* — come from the
+ * framework. This file only says how to build *your* application.
+ */
+import { run } from "@shaferllc/keel/cli";
+
+import { createApplication } from "../bootstrap/app.js";
+
+run(process.argv, { createApplication }).catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/templates/app/bootstrap/app.ts

@@ -0,0 +1,24 @@
+/**
+ * Application bootstrap. Creates the container, boots providers, loads routes.
+ * The server, the console, and the Worker all enter through here.
+ */
+
+import { Application, Router, HttpKernel, type ProviderClass } from "@shaferllc/keel/core";
+
+import { providers as nodeProviders } from "./providers.js";
+import { Kernel } from "../app/Http/Kernel.js";
+import registerWebRoutes from "../routes/web.js";
+
+export async function createApplication(providers: ProviderClass[] = nodeProviders): Promise<Application> {
+  const app = new Application(process.cwd());
+
+  // Binding our Kernel under HttpKernel is what makes `keel serve` use it. Without
+  // this the console falls back to a bare HttpKernel and the global middleware
+  // quietly vanishes.
+  app.singleton(HttpKernel, (container) => new Kernel(container as Application));
+
+  await app.boot(providers);
+  registerWebRoutes(app.make(Router));
+
+  return app;
+}

package/templates/app/bootstrap/providers.edge.ts

@@ -0,0 +1,15 @@
+import type { ProviderClass } from "@shaferllc/keel/core";
+import { AccountsServiceProvider } from "@shaferllc/keel/accounts";
+
+import { AppServiceProvider } from "../app/Providers/AppServiceProvider.js";
+
+/**
+ * Providers for the Worker.
+ *
+ * `DatabaseServiceProvider` is deliberately absent, and that's not an optimization —
+ * it's what keeps the build working. It reaches for `pg` and `@libsql/client`, which
+ * need `net`/`tls`; if the Worker's import graph touched it, wrangler would try to
+ * bundle a TCP driver for the edge and the deploy would fail. worker.ts binds D1
+ * before boot, so nothing here needs to open a connection.
+ */
+export const edgeProviders: ProviderClass[] = [AccountsServiceProvider, AppServiceProvider];

package/templates/app/bootstrap/providers.ts

@@ -0,0 +1,18 @@
+import type { ProviderClass } from "@shaferllc/keel/core";
+import { AccountsServiceProvider } from "@shaferllc/keel/accounts";
+
+import { AppServiceProvider } from "../app/Providers/AppServiceProvider.js";
+import { DatabaseServiceProvider } from "../app/Providers/DatabaseServiceProvider.js";
+
+/**
+ * Providers for the Node runtime (`keel serve`, the console, migrations).
+ *
+ * AccountsServiceProvider brings password reset, email verification, and two-factor —
+ * routes, migration and all. The flows live in the framework, tested once, rather
+ * than being copy-pasted into every app that has a login.
+ */
+export const providers: ProviderClass[] = [
+  DatabaseServiceProvider,
+  AccountsServiceProvider,
+  AppServiceProvider,
+];

package/templates/app/config/app.ts

@@ -0,0 +1,10 @@
+import { env } from "@shaferllc/keel/core";
+
+export default {
+  name: env("APP_NAME", "Keel App"),
+  env: env("APP_ENV", "local"),
+  debug: env("APP_DEBUG", true),
+  url: env("APP_URL", "http://localhost:3000"),
+  port: env("APP_PORT", 3000),
+  key: env("APP_KEY", ""),
+};

package/templates/app/config/database.ts

@@ -0,0 +1,42 @@
+import { env } from "@shaferllc/keel/core";
+
+/**
+ * Every driver, out of the box. `DB_CONNECTION` picks one.
+ *
+ * The default is `d1` in production — Cloudflare is where this is meant to run —
+ * and `sqlite` locally, so `npm run dev` needs no wrangler and no account. Both are
+ * SQLite, so one schema and one set of migrations serve both.
+ */
+export default {
+  default: env("DB_CONNECTION", "sqlite"),
+
+  connections: {
+    // Cloudflare D1. Inside the Worker the binding (env.DB) is used directly;
+    // migrations and scripts reach the same database over the HTTP API.
+    d1: {
+      driver: "d1",
+      binding: "DB",
+      accountId: env("CLOUDFLARE_ACCOUNT_ID", ""),
+      databaseId: env("D1_DATABASE_ID", ""),
+      apiToken: env("CLOUDFLARE_API_TOKEN", ""),
+    },
+
+    // A local file. Zero setup — this is what `npm run dev` uses.
+    sqlite: {
+      driver: "libsql",
+      url: env("DB_URL", "file:./database.sqlite"),
+    },
+
+    // libSQL over the network (Turso).
+    turso: {
+      driver: "libsql",
+      url: env("TURSO_URL", ""),
+      authToken: env("TURSO_AUTH_TOKEN", ""),
+    },
+
+    postgres: {
+      driver: "pg",
+      url: env("DATABASE_URL", ""),
+    },
+  },
+};

package/templates/app/database/migrations/0001_create_users.ts

@@ -0,0 +1,21 @@
+import type { Migration } from "@shaferllc/keel/core";
+
+const migration: Migration = {
+  name: "0001_create_users",
+
+  async up(schema) {
+    await schema.createTable("users", (t) => {
+      t.id();
+      t.string("name");
+      t.string("email").unique();
+      t.string("password");
+      t.timestamps();
+    });
+  },
+
+  async down(schema) {
+    await schema.dropTable("users");
+  },
+};
+
+export default migration;

package/templates/app/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "__APP_NAME__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "keel": "tsx bin/keel.ts",
+    "dev": "npm run css:build && concurrently -k -n css,web \"npm run css:watch\" \"tsx watch bin/keel.ts serve\"",
+    "serve": "tsx bin/keel.ts serve",
+    "dev:edge": "wrangler dev",
+    "deploy": "npm run css:build && wrangler deploy",
+    "migrate": "tsx bin/keel.ts migrate",
+    "css:build": "tailwindcss -i ./resources/css/app.css -o ./public/assets/app.css --minify",
+    "css:watch": "tailwindcss -i ./resources/css/app.css -o ./public/assets/app.css --watch",
+    "test": "tsx --test --test-concurrency=1 tests/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.13.7",
+    "@libsql/client": "^0.14.0",
+    "@shaferllc/keel": "__KEEL_VERSION__",
+    "hono": "^4.6.14",
+    "zod": "^3.24.1",
+    "pg": "^8.13.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "wrangler": "^4.0.0",
+    "@types/pg": "^8.11.10",
+    "@tailwindcss/cli": "^4.0.0",
+    "tailwindcss": "^4.0.0",
+    "concurrently": "^9.1.0"
+  }
+}

package/templates/app/public/.gitkeep

@@ -0,0 +1,2 @@
+Git does not track empty directories, and wrangler needs this one to exist
+(assets.directory). Built CSS lands in ./assets/ and is gitignored.

package/templates/app/resources/css/app.css

@@ -0,0 +1 @@
+@import "tailwindcss";

package/templates/app/resources/views/auth/forgot.tsx

@@ -0,0 +1,30 @@
+import Layout from "../layout.js";
+
+export default function Forgot({ sent }: { sent: boolean }) {
+  return (
+    <Layout title="Reset your password">
+      <main class="mx-auto flex min-h-screen max-w-sm flex-col justify-center gap-6 px-6">
+        <h1 class="text-2xl font-semibold tracking-tight">Reset your password</h1>
+
+        {sent ? (
+          // The same answer whether or not that address has an account — otherwise
+          // this page tells a stranger which emails are registered.
+          <p class="rounded-lg bg-slate-100 px-3 py-2 text-sm">
+            If that address has an account, a link is on its way.
+          </p>
+        ) : (
+          <form method="post" action="/forgot-password" class="flex flex-col gap-3">
+            <input
+              class="rounded-lg border border-slate-300 px-3 py-2"
+              type="email"
+              name="email"
+              placeholder="Email"
+              required
+            />
+            <button class="rounded-lg bg-slate-900 px-4 py-2 text-white">Send the link</button>
+          </form>
+        )}
+      </main>
+    </Layout>
+  );
+}

package/templates/app/resources/views/auth/login.tsx

@@ -0,0 +1,24 @@
+import Layout from "../layout.js";
+
+export default function Login({ error }: { error: string | null }) {
+  return (
+    <Layout title="Log in">
+      <main class="mx-auto flex min-h-screen max-w-sm flex-col justify-center gap-6 px-6">
+        <h1 class="text-2xl font-semibold tracking-tight">Log in</h1>
+
+        {error && <p class="rounded-lg bg-red-50 px-3 py-2 text-sm text-red-700">{error}</p>}
+
+        <form method="post" action="/login" class="flex flex-col gap-3">
+          <input class="rounded-lg border border-slate-300 px-3 py-2" type="email" name="email" placeholder="Email" required />
+          <input class="rounded-lg border border-slate-300 px-3 py-2" type="password" name="password" placeholder="Password" required />
+          <button class="rounded-lg bg-slate-900 px-4 py-2 text-white">Log in</button>
+        </form>
+
+        <p class="text-sm text-slate-500">
+          <a class="underline" href="/register">Register</a> ·{" "}
+          <a class="underline" href="/forgot-password">Forgot password?</a>
+        </p>
+      </main>
+    </Layout>
+  );
+}

package/templates/app/resources/views/auth/register.tsx

@@ -0,0 +1,24 @@
+import Layout from "../layout.js";
+
+export default function Register({ error }: { error: string | null }) {
+  return (
+    <Layout title="Register">
+      <main class="mx-auto flex min-h-screen max-w-sm flex-col justify-center gap-6 px-6">
+        <h1 class="text-2xl font-semibold tracking-tight">Register</h1>
+
+        {error && <p class="rounded-lg bg-red-50 px-3 py-2 text-sm text-red-700">{error}</p>}
+
+        <form method="post" action="/register" class="flex flex-col gap-3">
+          <input class="rounded-lg border border-slate-300 px-3 py-2" name="name" placeholder="Name" required />
+          <input class="rounded-lg border border-slate-300 px-3 py-2" type="email" name="email" placeholder="Email" required />
+          <input class="rounded-lg border border-slate-300 px-3 py-2" type="password" name="password" placeholder="Password" required />
+          <button class="rounded-lg bg-slate-900 px-4 py-2 text-white">Register</button>
+        </form>
+
+        <p class="text-sm text-slate-500">
+          Already have an account? <a class="underline" href="/login">Log in</a>
+        </p>
+      </main>
+    </Layout>
+  );
+}

package/templates/app/resources/views/auth/two-factor.tsx

@@ -0,0 +1,22 @@
+import Layout from "../layout.js";
+
+export default function TwoFactor({ error }: { error: string | null }) {
+  return (
+    <Layout title="Two-factor">
+      <main class="mx-auto flex min-h-screen max-w-sm flex-col justify-center gap-6 px-6">
+        <h1 class="text-2xl font-semibold tracking-tight">Two-factor</h1>
+
+        {error && <p class="rounded-lg bg-red-50 px-3 py-2 text-sm text-red-700">{error}</p>}
+
+        <form method="post" action="/two-factor" class="flex flex-col gap-3">
+          <input class="rounded-lg border border-slate-300 px-3 py-2" name="code" placeholder="6-digit code, or a recovery code" required autofocus />
+          <button class="rounded-lg bg-slate-900 px-4 py-2 text-white">Two-factor</button>
+        </form>
+
+        <p class="text-sm text-slate-500">
+          Your password was accepted. You are not signed in until this code checks out.
+        </p>
+      </main>
+    </Layout>
+  );
+}

package/templates/app/resources/views/dashboard.tsx

@@ -0,0 +1,20 @@
+import Layout from "./layout.js";
+
+export default function Dashboard({ name, twoFactor }: { name: string; twoFactor: boolean }) {
+  return (
+    <Layout title="Dashboard">
+      <main class="mx-auto max-w-2xl px-6 py-16">
+        <h1 class="text-3xl font-semibold tracking-tight">Hello, {name}.</h1>
+
+        <p class="mt-4 text-slate-600">
+          Two-factor is {twoFactor ? "on" : "off"}.{" "}
+          {!twoFactor && "POST /two-factor/enable to start setting it up."}
+        </p>
+
+        <form method="post" action="/logout" class="mt-8">
+          <button class="rounded-lg border border-slate-300 px-4 py-2">Log out</button>
+        </form>
+      </main>
+    </Layout>
+  );
+}

package/templates/app/resources/views/layout.tsx

@@ -0,0 +1,15 @@
+import type { PropsWithChildren } from "hono/jsx";
+
+export default function Layout({ title, children }: PropsWithChildren<{ title: string }>) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <title>{title}</title>
+        <link rel="stylesheet" href="/assets/app.css" />
+      </head>
+      <body class="min-h-screen bg-slate-50 text-slate-900 antialiased">{children}</body>
+    </html>
+  );
+}

package/templates/app/resources/views/welcome.tsx

@@ -0,0 +1,29 @@
+import Layout from "./layout.js";
+
+export default function Welcome({ signedIn }: { signedIn: boolean }) {
+  return (
+    <Layout title="Keel">
+      <main class="mx-auto flex min-h-screen max-w-2xl flex-col justify-center gap-6 px-6">
+        <h1 class="text-4xl font-semibold tracking-tight">Keel</h1>
+        <p class="text-slate-600">Sessions, password reset, and two-factor are already wired.</p>
+
+        <div class="flex gap-3">
+          {signedIn ? (
+            <a class="rounded-lg bg-slate-900 px-4 py-2 text-white" href="/dashboard">
+              Dashboard
+            </a>
+          ) : (
+            <>
+              <a class="rounded-lg bg-slate-900 px-4 py-2 text-white" href="/login">
+                Log in
+              </a>
+              <a class="rounded-lg border border-slate-300 px-4 py-2" href="/register">
+                Register
+              </a>
+            </>
+          )}
+        </div>
+      </main>
+    </Layout>
+  );
+}

package/templates/app/routes/web.ts

@@ -0,0 +1,35 @@
+import type { Router, Ctx } from "@shaferllc/keel/core";
+import { auth } from "@shaferllc/keel/core";
+
+import { AuthController } from "../app/Controllers/AuthController.js";
+import { DashboardController } from "../app/Controllers/DashboardController.js";
+import { HomeController } from "../app/Controllers/HomeController.js";
+
+/** Send guests to the login page. */
+const authenticated = async (c: Ctx, next: () => Promise<void>) => {
+  if (auth().guest()) return c.redirect("/login");
+  await next();
+};
+
+export default function routes(router: Router): void {
+  router.get("/", [HomeController, "index"]);
+  router.get("/health", (c: Ctx) => c.json({ ok: true }));
+
+  router.get("/login", [AuthController, "showLogin"]).name("login");
+  router.post("/login", [AuthController, "login"]);
+
+  router.get("/two-factor", [AuthController, "showTwoFactor"]);
+  router.post("/two-factor", [AuthController, "twoFactor"]);
+
+  router.get("/register", [AuthController, "showRegister"]).name("register");
+  router.post("/register", [AuthController, "register"]);
+
+  router.post("/logout", [AuthController, "logout"]).name("logout");
+
+  router.get("/forgot-password", [AuthController, "showForgot"]);
+  router.post("/forgot-password", [AuthController, "forgot"]);
+  router.post("/reset-password", [AuthController, "reset"]);
+
+  router.get("/dashboard", [DashboardController, "index"]).middleware(authenticated).name("dashboard");
+  router.post("/two-factor/enable", [DashboardController, "startTwoFactor"]).middleware(authenticated);
+}

package/templates/app/tests/auth.test.ts

@@ -0,0 +1,47 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { HttpKernel, testClient } from "@shaferllc/keel/core";
+
+import { createApplication } from "../bootstrap/app.js";
+
+/**
+ * These hit the real routes through the real kernel. A starter that ships no tests
+ * teaches that tests are optional — and auth is the last place you want that.
+ */
+test("a visitor can register and reach the dashboard", async () => {
+  const app = await createApplication();
+  const client = testClient(app.make(HttpKernel));
+
+  (await client.get("/login")).assertOk();
+
+  const registered = await client.form("/register", {
+    name: "Ada",
+    email: `ada+${crypto.randomUUID()}@example.com`,
+    password: "correct horse battery",
+  });
+
+  // A redirect to the dashboard means the session was set.
+  assert.equal(registered.status, 302);
+});
+
+test("the dashboard turns guests away", async () => {
+  const app = await createApplication();
+  const client = testClient(app.make(HttpKernel));
+
+  const response = await client.get("/dashboard");
+
+  assert.equal(response.status, 302, "a guest is redirected, not shown the page");
+});
+
+test("a wrong password says nothing about whether the account exists", async () => {
+  const app = await createApplication();
+  const client = testClient(app.make(HttpKernel));
+
+  const response = await client.form("/login", {
+    email: "nobody@example.com",
+    password: "wrong",
+  });
+
+  assert.equal(response.status, 401);
+});

package/templates/app/tsconfig.json

@@ -0,0 +1,31 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": [
+      "ES2022"
+    ],
+    "types": [
+      "node"
+    ],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "jsxImportSource": "hono/jsx"
+  },
+  "include": [
+    "app",
+    "bootstrap",
+    "config",
+    "routes",
+    "database",
+    "resources",
+    "bin",
+    "tests"
+  ]
+}

package/templates/app/worker.ts

@@ -0,0 +1,33 @@
+/**
+ * The Cloudflare Workers entry. `wrangler dev` / `wrangler deploy` use this.
+ *
+ * D1's binding only exists inside a request, so the connection is wired here, before
+ * the app boots — and the app is built once, then reused.
+ *
+ * Note the provider list: `edgeProviders`, not the Node one. See providers.edge.ts.
+ */
+
+import { setConnection, HttpKernel } from "@shaferllc/keel/core";
+import { d1Connection, type D1Like } from "@shaferllc/keel/db/d1";
+
+import { createApplication } from "./bootstrap/app.js";
+import { edgeProviders } from "./bootstrap/providers.edge.js";
+
+interface Env {
+  DB: D1Like;
+}
+
+let handler: { fetch: (request: Request, env: unknown) => Response | Promise<Response> } | undefined;
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    if (!handler) {
+      setConnection(d1Connection(env.DB), "sqlite");
+
+      const app = await createApplication(edgeProviders);
+      handler = app.make(HttpKernel).build();
+    }
+
+    return handler.fetch(request, env);
+  },
+};