@shaferllc/keel 0.82.0 → 0.83.0

package/templates/app/wrangler.jsonc

@@ -0,0 +1,25 @@
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "__APP_NAME__",
+  "main": "worker.ts",
+  "compatibility_date": "2025-01-01",
+  // AsyncLocalStorage — Keel carries the request, the open transaction, and the
+  // current team in it. Without this flag they have nowhere to live.
+  "compatibility_flags": ["nodejs_compat"],
+
+  // The compiled stylesheet. Cloudflare serves these; the Worker never sees them.
+  "assets": { "directory": "./public" },
+
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "__APP_NAME__",
+      // Create one: wrangler d1 create __APP_NAME__ — then paste the id here.
+      "database_id": ""
+    }
+  ],
+
+  "vars": {
+    "DB_CONNECTION": "d1"
+  }
+}

package/templates/minimal/.env.example

@@ -0,0 +1,8 @@
+APP_NAME="Keel App"
+APP_ENV=local
+APP_DEBUG=true
+APP_URL=http://localhost:3000
+APP_PORT=3000
+
+# Signs cookies, sessions, and encrypted payloads. Generate one: keel key:generate
+APP_KEY=

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

@@ -0,0 +1,14 @@
+import type { Ctx } from "@shaferllc/keel/core";
+import { view } from "@shaferllc/keel/core";
+
+import Welcome from "../../resources/views/welcome.js";
+
+export class HomeController {
+  index(c: Ctx) {
+    return c.json({ message: "Keel is running." });
+  }
+
+  async welcome(c: Ctx) {
+    return c.html(await view(Welcome, { name: "world" }));
+  }
+}

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

@@ -0,0 +1,22 @@
+import { HttpKernel, serveStatic } 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 (where
+ * Cloudflare serves the assets itself and this simply falls through).
+ *
+ * Files resolve as `root + path`, so /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" }));
+  }
+}

package/templates/minimal/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/minimal/app/Providers/AppServiceProvider.ts

@@ -0,0 +1,8 @@
+import { ServiceProvider } from "@shaferllc/keel/core";
+
+/** Bind your own services here. */
+export class AppServiceProvider extends ServiceProvider {
+  register(): void {}
+
+  boot(): void {}
+}

package/templates/minimal/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/minimal/bootstrap/app.ts

@@ -0,0 +1,24 @@
+/**
+ * Application bootstrap. Creates the container, boots providers, loads routes.
+ * Both the server and the console enter through here.
+ */
+
+import { Application, Router, HttpKernel } from "@shaferllc/keel/core";
+
+import { providers } from "./providers.js";
+import { Kernel } from "../app/Http/Kernel.js";
+import registerWebRoutes from "../routes/web.js";
+
+export async function createApplication(): 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 your 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/minimal/bootstrap/providers.ts

@@ -0,0 +1,6 @@
+import type { ProviderClass } from "@shaferllc/keel/core";
+
+import { AppServiceProvider } from "../app/Providers/AppServiceProvider.js";
+
+/** Service providers loaded on every request and command, in order. */
+export const providers: ProviderClass[] = [AppServiceProvider];

package/templates/minimal/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/minimal/package.json

@@ -0,0 +1,29 @@
+{
+  "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",
+    "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",
+    "typecheck": "tsc --noEmit",
+    "dev:edge": "wrangler dev",
+    "deploy": "npm run css:build && wrangler deploy"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.13.7",
+    "@shaferllc/keel": "__KEEL_VERSION__",
+    "hono": "^4.6.14"
+  },
+  "devDependencies": {
+    "@tailwindcss/cli": "^4.0.0",
+    "@types/node": "^22.10.0",
+    "concurrently": "^9.1.0",
+    "tailwindcss": "^4.0.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "wrangler": "^4.0.0"
+  }
+}

package/templates/minimal/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/minimal/resources/css/app.css

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

package/templates/minimal/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-white text-slate-900 antialiased">{children}</body>
+    </html>
+  );
+}

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

@@ -0,0 +1,15 @@
+import Layout from "./layout.js";
+
+export default function Welcome({ name }: { name: string }) {
+  return (
+    <Layout title="Keel">
+      <main class="mx-auto flex min-h-screen max-w-2xl flex-col justify-center gap-4 px-6">
+        <h1 class="text-4xl font-semibold tracking-tight">Hello, {name}.</h1>
+        <p class="text-slate-600">
+          This is a JSX view, rendered on the server. Edit{" "}
+          <code class="rounded bg-slate-100 px-1.5 py-0.5 text-sm">resources/views/welcome.tsx</code>.
+        </p>
+      </main>
+    </Layout>
+  );
+}

package/templates/minimal/routes/web.ts

@@ -0,0 +1,13 @@
+import type { Router, Ctx } from "@shaferllc/keel/core";
+
+import { HomeController } from "../app/Controllers/HomeController.js";
+
+/**
+ * Handlers are a [Controller, method] tuple (resolved from the container) or an
+ * inline closure.
+ */
+export default function routes(router: Router): void {
+  router.get("/", [HomeController, "index"]);
+  router.get("/welcome", [HomeController, "welcome"]);
+  router.get("/hello/:name", (c: Ctx) => c.text(`Hello, ${c.req.param("name")}!`));
+}

package/templates/minimal/tsconfig.json

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

package/templates/minimal/worker.ts

@@ -0,0 +1,23 @@
+/**
+ * The Cloudflare Workers entry. `wrangler dev` / `wrangler deploy` use this;
+ * `keel serve` (Node) does not.
+ *
+ * The app is built once and reused across requests.
+ */
+
+import { HttpKernel } from "@shaferllc/keel/core";
+
+import { createApplication } from "./bootstrap/app.js";
+
+let handler: { fetch: (request: Request, env: unknown) => Response | Promise<Response> } | undefined;
+
+export default {
+  async fetch(request: Request, env: unknown): Promise<Response> {
+    if (!handler) {
+      const app = await createApplication();
+      handler = app.make(HttpKernel).build();
+    }
+
+    return handler.fetch(request, env);
+  },
+};

package/templates/minimal/wrangler.jsonc

@@ -0,0 +1,10 @@
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "__APP_NAME__",
+  "main": "worker.ts",
+  "compatibility_date": "2025-01-01",
+  // AsyncLocalStorage — Keel carries the request context in it.
+  "compatibility_flags": ["nodejs_compat"],
+
+  "assets": { "directory": "./public" }
+}

package/templates/saas/.env.example

@@ -0,0 +1,12 @@
+APP_NAME="Keel API"
+APP_ENV=local
+APP_DEBUG=true
+APP_URL=http://localhost:3000
+APP_PORT=3000
+
+# Signs tokens and encrypted payloads. Generate one: keel key:generate
+APP_KEY=
+
+# A file is enough to start; point this at Postgres when you outgrow it.
+DB_CONNECTION=sqlite
+DB_URL=file:./database.sqlite

package/templates/saas/app/Controllers/AuthController.ts

@@ -0,0 +1,125 @@
+import type { Ctx } from "@shaferllc/keel/core";
+import { auth, hash, session, validate, view } from "@shaferllc/keel/core";
+import { attempt, completeTwoFactor, requestPasswordReset, resetPassword } from "@shaferllc/keel/accounts";
+import { createTeam, switchTeam } from "@shaferllc/keel/teams";
+import { z } from "zod";
+
+import { User } from "../Models/User.js";
+import Login from "../../resources/views/auth/login.js";
+import Register from "../../resources/views/auth/register.js";
+import TwoFactor from "../../resources/views/auth/two-factor.js";
+import Forgot from "../../resources/views/auth/forgot.js";
+
+const Credentials = z.object({
+  email: z.string().email(),
+  password: z.string().min(1),
+});
+
+const NewUser = z.object({
+  name: z.string().min(1),
+  email: z.string().email(),
+  password: z.string().min(8),
+});
+
+export class AuthController {
+  async showLogin(c: Ctx) {
+    return c.html(await view(Login, { error: null }));
+  }
+
+  async login(c: Ctx) {
+    const { email, password } = await validate(Credentials, await c.req.parseBody());
+
+    const result = await attempt(email, password);
+
+    if (result.status === "failed") {
+      // One message for a wrong email and a wrong password — anything more specific
+      // tells a stranger which addresses have accounts here.
+      return c.html(await view(Login, { error: "Those credentials don't match." }), 401);
+    }
+
+    if (result.status === "two-factor") {
+      // NOT a session. Nothing is logged in until the code checks out.
+      session().put("2fa_challenge", result.challenge);
+      return c.redirect("/two-factor");
+    }
+
+    auth().login(result.user.id);
+    return c.redirect("/dashboard");
+  }
+
+  async showTwoFactor(c: Ctx) {
+    return c.html(await view(TwoFactor, { error: null }));
+  }
+
+  async twoFactor(c: Ctx) {
+    const body = await c.req.parseBody();
+    const challenge = session().get("2fa_challenge") as string | undefined;
+
+    if (!challenge) return c.redirect("/login");
+
+    const user = await completeTwoFactor(challenge, String(body.code ?? ""));
+
+    if (!user) {
+      return c.html(await view(TwoFactor, { error: "That code isn't valid." }), 401);
+    }
+
+    session().forget("2fa_challenge");
+    auth().login(user.id);
+
+    return c.redirect("/dashboard");
+  }
+
+  async showRegister(c: Ctx) {
+    return c.html(await view(Register, { error: null }));
+  }
+
+  async register(c: Ctx) {
+    const data = await validate(NewUser, await c.req.parseBody());
+
+    if (await User.query().where("email", data.email.toLowerCase()).first()) {
+      return c.html(await view(Register, { error: "That email is already registered." }), 422);
+    }
+
+    const user = await User.create({
+      name: data.name,
+      email: data.email.toLowerCase(),
+      password: await hash.make(data.password),
+    });
+
+    // A personal team, immediately. Without one the user has no tenant, and every
+    // TenantModel query throws — which is exactly what it should do, so the fix is
+    // to give them a team rather than to soften the scope. A solo user is a team of
+    // one; adding tenancy later means backfilling every table.
+    const team = await createTeam(`${data.name}'s team`, user.id);
+    await switchTeam(user.id, team.id);
+
+    auth().login(user.id);
+    return c.redirect("/teams");
+  }
+
+  logout(c: Ctx) {
+    auth().logout();
+    return c.redirect("/");
+  }
+
+  async showForgot(c: Ctx) {
+    return c.html(await view(Forgot, { sent: false }));
+  }
+
+  async forgot(c: Ctx) {
+    const body = await c.req.parseBody();
+    await requestPasswordReset(String(body.email ?? ""));
+
+    // The same answer whether or not that address has an account.
+    return c.html(await view(Forgot, { sent: true }));
+  }
+
+  async reset(c: Ctx) {
+    const body = await c.req.parseBody();
+
+    const ok = await resetPassword(String(body.token ?? ""), String(body.password ?? ""));
+    if (!ok) return c.text("That reset link is invalid or has expired.", 422);
+
+    return c.redirect("/login");
+  }
+}

package/templates/saas/app/Controllers/DashboardController.ts

@@ -0,0 +1,37 @@
+import type { Ctx } from "@shaferllc/keel/core";
+import { auth, view } from "@shaferllc/keel/core";
+import { enableTwoFactor, hasTwoFactor } from "@shaferllc/keel/accounts";
+
+import type { User } from "../Models/User.js";
+import Dashboard from "../../resources/views/dashboard.js";
+
+export class DashboardController {
+  async index(c: Ctx) {
+    const user = await auth().user<User>();
+    if (!user) return c.redirect("/login");
+
+    return c.html(
+      await view(Dashboard, {
+        name: user.name,
+        twoFactor: hasTwoFactor(user as never),
+      }),
+    );
+  }
+
+  /** Step one of turning 2FA on: a secret and recovery codes. It is NOT on yet. */
+  async startTwoFactor(c: Ctx) {
+    const user = await auth().user<User>();
+    if (!user) return c.redirect("/login");
+
+    const setup = await enableTwoFactor(user as never, { issuer: "Keel App" });
+
+    // Render setup.uri to a QR code locally — it contains the shared secret, so it
+    // must never be sent to a third-party QR service.
+    return c.json({
+      uri: setup.uri,
+      secret: setup.secret,
+      recoveryCodes: setup.recoveryCodes,
+      next: "POST /two-factor/confirm with a code from your authenticator to turn it on.",
+    });
+  }
+}

package/templates/saas/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/saas/app/Controllers/TeamController.ts

@@ -0,0 +1,88 @@
+import type { Ctx } from "@shaferllc/keel/core";
+import { auth, view } from "@shaferllc/keel/core";
+import {
+  acceptInvitation,
+  createTeam,
+  currentTeam,
+  invite,
+  pendingInvitations,
+  switchTeam,
+  teamsFor,
+  type Role,
+} from "@shaferllc/keel/teams";
+
+import type { User } from "../Models/User.js";
+import { Project } from "../Models/Project.js";
+import Teams from "../../resources/views/teams/index.js";
+
+export class TeamController {
+  async index(c: Ctx) {
+    const user = await auth().user<User>();
+    if (!user) return c.redirect("/login");
+
+    const teamId = currentTeam();
+
+    return c.html(
+      await view(Teams, {
+        teams: (await teamsFor(user.id)).map((t) => ({ id: t.id, name: t.name })),
+        current: typeof teamId === "number" ? teamId : null,
+        // Scoped automatically — this is the current team's projects, and there is
+        // no `where` to forget.
+        projects: (await Project.all()).map((p) => ({ id: p.id, name: p.name })),
+        invitations: teamId ? await pendingInvitations(teamId) : [],
+      }),
+    );
+  }
+
+  async store(c: Ctx) {
+    const user = await auth().user<User>();
+    if (!user) return c.redirect("/login");
+
+    const body = await c.req.parseBody();
+    await createTeam(String(body.name ?? "New team"), user.id);
+
+    return c.redirect("/teams");
+  }
+
+  async switch(c: Ctx) {
+    const user = await auth().user<User>();
+    if (!user) return c.redirect("/login");
+
+    const body = await c.req.parseBody();
+
+    // Returns false for a team they aren't in — the check is the point.
+    await switchTeam(user.id, Number(body.team_id));
+
+    return c.redirect("/teams");
+  }
+
+  async invite(c: Ctx) {
+    const teamId = currentTeam();
+    if (typeof teamId !== "number") return c.redirect("/teams");
+
+    const body = await c.req.parseBody();
+    await invite(teamId, String(body.email ?? ""), (body.role as Role) ?? "member");
+
+    return c.redirect("/teams");
+  }
+
+  async accept(c: Ctx) {
+    const user = await auth().user<User>();
+    if (!user) return c.redirect("/login");
+
+    // The invited address is re-checked, so a forwarded link can't be redeemed by
+    // whoever happens to hold it.
+    const team = await acceptInvitation(c.req.param("token") ?? "", user.id, user.email);
+
+    return team ? c.redirect("/teams") : c.text("That invitation is invalid or has expired.", 422);
+  }
+
+  async createProject(c: Ctx) {
+    const body = await c.req.parseBody();
+
+    // Stamped with the current team by TenantModel — no team_id here on purpose.
+    await Project.create({ name: String(body.name ?? "Untitled") });
+
+    return c.redirect("/teams");
+  }
+}

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

@@ -0,0 +1,27 @@
+import { HttpKernel, serveStatic, sessionMiddleware } from "@shaferllc/keel/core";
+import type { Application } from "@shaferllc/keel/core";
+import { teamContext } from "@shaferllc/keel/teams";
+
+import { requestLogger } from "./Middleware/requestLogger.js";
+
+/**
+ * Global middleware — runs on every request, in order.
+ *
+ * `teamContext()` puts the request inside the signed-in user's current team, which
+ * is what scopes every `TenantModel` without a single handler doing anything. It
+ * verifies membership rather than trusting `users.current_team_id` — that column is
+ * a number on a row the user can influence, so switching teams would otherwise be a
+ * matter of writing someone else's id into it.
+ *
+ * It must run after the session, or there's no user to resolve a team for.
+ */
+export class Kernel extends HttpKernel {
+  constructor(app: Application) {
+    super(app);
+
+    this.use(requestLogger);
+    this.use(serveStatic({ root: "./public" }));
+    this.use(sessionMiddleware());
+    this.use(teamContext());
+  }
+}

package/templates/saas/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/saas/app/Models/Project.ts

@@ -0,0 +1,20 @@
+import { TenantModel } from "@shaferllc/keel/teams";
+
+/**
+ * A project belongs to a team — and cannot be seen outside it.
+ *
+ * Extending `TenantModel` (not `Model`) is the entire difference. Reads are
+ * constrained by an inherited global scope, so even `Project.find(id)` returns null
+ * for another team's row; writes are stamped with the current team, so a project
+ * can't be born ownerless. You never write `.where("team_id", …)`, which means you
+ * can never forget it.
+ */
+export class Project extends TenantModel {
+  static override table = "projects";
+  static override fillable = ["name"];
+  static override timestamps = true;
+
+  declare id: number;
+  declare name: string;
+  declare team_id: number;
+}

package/templates/saas/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/saas/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)));
+  }
+}