@awsmbiz/create-inbis-app 0.0.0-stage → 0.1.0

package/template/modules/example/wiring/admin/worker.routes.ts

@@ -0,0 +1,2 @@
+// EXAMPLE CODE (example module, src/example-notes-admin.ts): the notes admin API. Copy or delete.
+mountExampleNotesAdmin(app);

package/template/modules/example/wiring/audit/audit.catalogues.imports.ts

@@ -0,0 +1 @@
+import { EXAMPLE_AUDIT_ACTIONS } from "./example-audit-actions.js";

package/template/modules/example/wiring/audit/audit.catalogues.ts

@@ -0,0 +1,2 @@
+// The notes example's actions (example module: example code, delete with it).
+EXAMPLE_AUDIT_ACTIONS,

package/template/modules/example/wiring/audit/readme.modules.md

@@ -0,0 +1,4 @@
+With the audit trail (the `audit` module), adding a note records `example.note.created` and
+deleting one (admin area) `example.note.deleted`, with the note as the subject
+(`example_note:<id>`) and the signed-in user, if any, as the actor. The actions are declared
+in `src/example-audit-actions.ts` and registered in `src/audit-catalogues.ts`.

package/template/modules/example/wiring/readme.modules.md

@@ -0,0 +1,16 @@
+## Example notes (example code)
+
+A small business feature to copy for your own, or delete. Everything it adds is marked
+`EXAMPLE CODE`:
+
+- **Migration:** `migrations/0002_example_notes.sql` (the `example_note` table, in the app's
+  own migrations, applied after the platform's).
+- **API:** `src/example-notes.ts` mounts `GET /v1/example/notes` (newest first) and
+  `POST /v1/example/notes` (`{ title, body? }`, validated: `422 VALIDATION_FAILED`), both in
+  `/openapi.json`. Its `policy` decides who may call them.
+- **Screen:** `web/src/example-notes.tsx` at `/notes`, its strings under `notes.*` in
+  `web/src/messages.ts`; tests in `test/example-notes.test.ts` and `e2e/example-notes.spec.ts`.
+
+To delete it: remove those files, the `mountExampleNotes` call in `src/app.ts`, the `/notes`
+route in `web/src/routes.tsx` and the `notes.*` messages, then add a migration that drops
+`example_note` if one was applied anywhere (never delete an applied migration).

package/template/modules/example/wiring/web.messages.ts

@@ -0,0 +1,19 @@
+// Notes (example module: example code, copy or delete).
+"notes.title": "Notes",
+"notes.description": "Short notes kept by this app. An example feature: copy it for your own, or delete it.",
+"notes.add": "Add a note",
+"notes.noteTitle": "Title",
+"notes.noteBody": "Note",
+"notes.save": "Add note",
+"notes.saving": "Adding…",
+"notes.saved": "Added “{title}”.",
+"notes.saveFailed": "The note could not be added. Check the title and try again.",
+"notes.saveForbidden": "You can't add notes. Ask an administrator for access.",
+"notes.listHeading": "Latest notes",
+"notes.loading": "Loading notes…",
+"notes.empty": "No notes yet.",
+"notes.failed": "Notes could not be loaded.",
+"notes.failedHint": "Check your connection and try again.",
+"notes.tryAgain": "Try again",
+"notes.forbidden": "You can't see notes.",
+"notes.forbiddenHint": "Sign in with an account that has access, or ask an administrator.",

package/template/modules/example/wiring/web.routes.imports.tsx

@@ -0,0 +1 @@
+import { ExampleNotes } from "./example-notes.js";

package/template/modules/example/wiring/web.routes.tsx

@@ -0,0 +1,2 @@
+// EXAMPLE CODE (example module, web/src/example-notes.tsx): the notes screen. Copy or delete.
+{ path: "/notes", title: "notes.title", nav: true, render: () => <ExampleNotes /> },

package/template/modules/example/wiring/worker.imports.ts

@@ -0,0 +1 @@
+import { mountExampleNotes } from "./example-notes.js";

package/template/modules/example/wiring/worker.routes.ts

@@ -0,0 +1,2 @@
+// EXAMPLE CODE (example module, src/example-notes.ts): GET|POST /v1/example/notes. Copy or delete.
+mountExampleNotes(app, deps);

package/template/modules/example/with-access-control/test/example-notes-access.test.ts

@@ -0,0 +1,51 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { choicesWith, json, migrate, newUser, seedAdmin, seedUser, signIn, testApp, type TestApp } from "./auth-fixtures.js";
+
+// EXAMPLE CODE (example module, with access-control): the notes routes need sign-in and the
+// notes permissions. Delete it with the example.
+
+const NOTES = "/v1/example/notes";
+
+beforeEach(async () => {
+  await migrate();
+});
+
+async function signedInUser(app: TestApp): Promise<{ cookie: string; id: string }> {
+  const user = newUser();
+  await seedUser(user);
+  const cookie = await signIn(app, user);
+  const me = await app.call("/api/me", { headers: { cookie } });
+  return { cookie, id: (await me.json<{ user: { id: string } }>()).user.id };
+}
+
+describe("the example notes routes with access control", () => {
+  it("refuse a visitor who is not signed in", async () => {
+    const response = await testApp().call(NOTES);
+    expect(response.status).toBe(401);
+    expect(await response.json()).toMatchObject({ error: { code: "UNAUTHENTICATED" } });
+  });
+
+  it("refuse a signed-in user without the notes permissions", async () => {
+    const app = testApp(choicesWith("invite-only"));
+    const { cookie } = await signedInUser(app);
+    const read = await app.call(NOTES, { headers: { cookie } });
+    expect(read.status).toBe(403);
+    expect(await read.json()).toMatchObject({ error: { code: "FORBIDDEN", details: { permission: "example.notes.read" } } });
+    const write = await app.call(NOTES, json({ title: "Refused" }, { cookie }));
+    expect(write.status).toBe(403);
+  });
+
+  it("admit a user granted the notes-editor role, who is recorded as the author", async () => {
+    const app = testApp(choicesWith("invite-only"));
+    const user = await signedInUser(app);
+    const admin = await seedAdmin();
+    const granted = await app.call(`/api/admin/users/${user.id}/roles/notes-editor`, { ...json({}, { cookie: admin }), method: "PUT" });
+    expect(granted.status).toBe(200);
+
+    const added = await app.call(NOTES, json({ title: "Mine" }, { cookie: user.cookie }));
+    expect(added.status).toBe(201);
+    expect(await added.json()).toMatchObject({ title: "Mine", authorId: user.id });
+    const read = await app.call(NOTES, { headers: { cookie: user.cookie } });
+    expect(read.status).toBe(200);
+  });
+});

package/template/modules/example/with-admin/e2e/example-notes-admin.spec.ts

@@ -0,0 +1,55 @@
+import { expect, test, type BrowserContext } from "@playwright/test";
+import { adminApi } from "./auth-helpers.js";
+import { adminsCanSignIn } from "./auth-seeded.js";
+import { expectNoPageScroll, expectNoViolations, THEMES, VIEWPORTS } from "./axe.js";
+
+// EXAMPLE CODE (example module, with admin): the admin area's Notes page, as the seeded
+// administrator (signed in once, through the API). Delete it with the example.
+
+test.skip(!adminsCanSignIn, "administrators need email + password and 2FA (src/auth-choices.ts)");
+test.describe.configure({ mode: "serial" });
+
+let session: Awaited<ReturnType<BrowserContext["storageState"]>>;
+const title = `Moderated ${String(Date.now())}`;
+
+test.beforeAll(async ({ playwright, baseURL }) => {
+  const admin = await adminApi(playwright, baseURL);
+  // The note to delete. With access control, adding one needs the notes-editor role.
+  const { user } = (await (await admin.get("/api/me")).json()) as { user: { id: string } };
+  await admin.put(`/api/admin/users/${user.id}/roles/notes-editor`);
+  expect((await admin.post("/v1/example/notes", { data: { title } })).status()).toBe(201);
+  session = await admin.storageState();
+  await admin.dispose();
+});
+
+test.beforeEach(async ({ context }) => {
+  await context.addCookies(session.cookies);
+});
+
+test("an administrator deletes a note from the Notes page", async ({ page }) => {
+  await page.goto("/admin");
+  await page.getByRole("link", { name: "Notes" }).click();
+  await expect(page.getByRole("heading", { name: "Notes", level: 1 })).toBeVisible();
+  const notes = page.getByRole("list", { name: "Notes" });
+  await expect(notes).toContainText(title);
+  await page.getByRole("button", { name: `Delete “${title}”` }).click();
+  const dialog = page.getByRole("alertdialog");
+  await expect(dialog).toContainText(title);
+  await dialog.getByRole("button", { name: "Delete" }).click();
+  await expect(dialog).toBeHidden();
+  await expect(page.getByText(title)).toHaveCount(0);
+});
+
+for (const theme of THEMES) {
+  for (const [viewport, size] of Object.entries(VIEWPORTS)) {
+    test(`Admin notes (${theme}, ${viewport}) has no accessibility violations`, async ({ page }) => {
+      await page.emulateMedia({ colorScheme: theme });
+      await page.setViewportSize(size);
+      await page.goto("/admin/notes");
+      await expect(page.getByRole("heading", { name: "Notes", level: 1 })).toBeVisible();
+      await expect(page.getByText("Loading notes…")).toBeHidden();
+      await expectNoPageScroll(page);
+      await expectNoViolations(page);
+    });
+  }
+}

package/template/modules/example/with-admin/src/example-notes-admin.ts

@@ -0,0 +1,62 @@
+import { createRoute, z, type OpenAPIHono } from "@hono/zod-openapi";
+import type { ApiEnv } from "@awsmbiz/inbis-api";
+import { requireAdmin, requireRecentAdminSignIn, type AuthEnv } from "@awsmbiz/inbis-auth/hono";
+import { AppError } from "@awsmbiz/inbis-core";
+import { desc, eq } from "drizzle-orm";
+import type { Context } from "hono";
+import { EXAMPLE_AUDIT_ACTIONS } from "./example-audit-actions.js";
+import { exampleNote, NoteSchema, notesDatabase, recordNoteEvent, toNote } from "./example-notes.js";
+
+// EXAMPLE CODE (example module, with admin): the notes admin API behind the admin area's
+// Notes page (web/src/admin-notes.tsx). Copy it for your own admin routes, or delete it.
+
+const NoteListSchema = z.object({ items: z.array(NoteSchema) }).openapi("ExampleNoteAdminList");
+
+/** The newest notes the admin page shows. A real feature would paginate. */
+const LIST_LIMIT = 100;
+
+const list = createRoute({
+  method: "get",
+  path: "/api/admin/example/notes",
+  tags: ["example"],
+  summary: "The newest example notes, for administrators (example code)",
+  middleware: [requireAdmin()],
+  responses: {
+    200: { description: "Up to 100 notes, newest first", content: { "application/json": { schema: NoteListSchema } } },
+  },
+});
+
+const remove = createRoute({
+  method: "delete",
+  path: "/api/admin/example/notes/{noteId}",
+  tags: ["example"],
+  summary: "Delete an example note, for administrators (example code)",
+  middleware: [requireAdmin(), requireRecentAdminSignIn()],
+  request: { params: z.object({ noteId: z.string().min(1) }) },
+  responses: {
+    204: { description: "Deleted" },
+    404: { description: "No such note" },
+  },
+});
+
+/**
+ * Mounts the notes admin API, after the admin module's `mountAppAdmin` (auth's session
+ * middleware covers `/api/*`): `GET /api/admin/example/notes` (administrators) and
+ * `DELETE /api/admin/example/notes/:noteId` (also a recent sign-in; recorded in the audit
+ * trail when the app has one, as `example.note.deleted`).
+ */
+export function mountExampleNotesAdmin(app: OpenAPIHono<ApiEnv<Env>>): void {
+  app.openapi(list, async (c) => {
+    const rows = await notesDatabase(c).select().from(exampleNote).orderBy(desc(exampleNote.createdAt), desc(exampleNote.id)).limit(LIST_LIMIT);
+    return c.json({ items: rows.map(toNote) }, 200);
+  });
+
+  app.openapi(remove, async (c) => {
+    const { noteId } = c.req.valid("param");
+    const [row] = await notesDatabase(c).delete(exampleNote).where(eq(exampleNote.id, noteId)).returning({ id: exampleNote.id });
+    if (row === undefined) throw new AppError({ code: "NOT_FOUND", status: 404, message: "There is no such note." });
+    const actorId = (c as unknown as Context<AuthEnv>).var.user?.id ?? null;
+    await recordNoteEvent(c, EXAMPLE_AUDIT_ACTIONS.noteDeleted, actorId, row.id);
+    return c.body(null, 204);
+  });
+}

package/template/modules/example/with-admin/test/example-notes-admin.test.ts

@@ -0,0 +1,42 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { choicesWith, json, migrate, newUser, seedAdmin, seedUser, signIn, testApp } from "./auth-fixtures.js";
+import { notesCaller, postJson } from "./example-notes-fixtures.js";
+
+// EXAMPLE CODE (example module, with admin): the notes admin API. Delete it with the example.
+
+const ADMIN_NOTES = "/api/admin/example/notes";
+
+beforeEach(async () => {
+  await migrate();
+});
+
+describe("the example notes admin API", () => {
+  it("lets an administrator list notes and delete one", async () => {
+    const call = await notesCaller();
+    const { id } = await (await call("/v1/example/notes", postJson({ title: "To moderate" }))).json<{ id: string }>();
+    const app = testApp(choicesWith("invite-only"));
+    const admin = await seedAdmin();
+
+    const listed = await app.call(ADMIN_NOTES, { headers: { cookie: admin } });
+    expect(listed.status).toBe(200);
+    const { items } = await listed.json<{ items: { id: string; title: string }[] }>();
+    expect(items.find((note) => note.id === id)).toMatchObject({ title: "To moderate" });
+
+    const deleted = await app.call(`${ADMIN_NOTES}/${id}`, { ...json({}, { cookie: admin }), method: "DELETE" });
+    expect(deleted.status).toBe(204);
+    const after = await (await app.call(ADMIN_NOTES, { headers: { cookie: admin } })).json<{ items: { id: string }[] }>();
+    expect(after.items.map((note) => note.id)).not.toContain(id);
+
+    const again = await app.call(`${ADMIN_NOTES}/${id}`, { ...json({}, { cookie: admin }), method: "DELETE" });
+    expect(again.status).toBe(404);
+  });
+
+  it("is for administrators only", async () => {
+    const app = testApp(choicesWith("invite-only"));
+    expect((await app.call(ADMIN_NOTES)).status).toBe(401);
+    const user = newUser();
+    await seedUser(user);
+    const cookie = await signIn(app, user);
+    expect((await app.call(ADMIN_NOTES, { headers: { cookie } })).status).toBe(403);
+  });
+});

package/template/modules/example/with-admin/web/src/admin-notes.tsx

@@ -0,0 +1,99 @@
+import { ConfirmDialog, EmptyState, ErrorState, LoadingState, PageHeader, useAdmin } from "@awsmbiz/inbis-admin-ui";
+import { ApiError } from "@awsmbiz/inbis-api-client";
+import { Button, Card, CardContent } from "@awsmbiz/inbis-ui";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { NotebookPen } from "lucide-react";
+import { useRef, useState } from "react";
+import { getJson } from "./admin-client.js";
+import { t } from "./messages.js";
+
+// EXAMPLE CODE (example module, with admin): the admin area's Notes page, on the notes admin
+// API (src/example-notes-admin.ts). Copy it for an admin page of your own, or delete it.
+
+export { NotebookPen as NotesIcon };
+
+interface Note {
+  id: string;
+  title: string;
+  body: string;
+  createdAt: string;
+}
+
+const dateFormat = new Intl.DateTimeFormat(undefined, { dateStyle: "medium", timeStyle: "short" });
+
+async function deleteNote(id: string): Promise<void> {
+  let response: Response;
+  try {
+    response = await fetch(`/api/admin/example/notes/${encodeURIComponent(id)}`, { method: "DELETE", credentials: "include" });
+  } catch (cause) {
+    throw ApiError.network(cause);
+  }
+  if (!response.ok) throw await ApiError.fromResponse(response);
+}
+
+/** Notes: the newest notes, each with a Delete action (confirmed first). */
+export function NotesAdminPage() {
+  const { withStepUp } = useAdmin();
+  const queryClient = useQueryClient();
+  const [deleting, setDeleting] = useState<Note | null>(null);
+  const list = useRef<HTMLUListElement>(null);
+  const notes = useQuery({
+    queryKey: ["example", "notes"],
+    queryFn: ({ signal }) => withStepUp(() => getJson<{ items: Note[] }>("/api/admin/example/notes", { signal })),
+  });
+
+  return (
+    <>
+      <PageHeader title={t("admin.notes.title")} description={t("admin.notes.description")} />
+      {notes.isPending ? <LoadingState label={t("admin.notes.loading")} /> : null}
+      {notes.isError ? <ErrorState title={t("admin.notes.failed")} error={notes.error} onRetry={() => void notes.refetch()} /> : null}
+      {notes.isSuccess && notes.data.items.length === 0 ? <EmptyState title={t("admin.notes.empty")} /> : null}
+      {notes.isSuccess && notes.data.items.length > 0 ? (
+        <Card>
+          <CardContent>
+            <ul ref={list} tabIndex={-1} aria-label={t("admin.notes.listLabel")} className="flex flex-col divide-y outline-none">
+              {notes.data.items.map((note) => (
+                <li key={note.id} className="flex flex-col gap-2 py-3 first:pt-0 last:pb-0 sm:flex-row sm:items-start sm:justify-between">
+                  <div className="flex min-w-0 flex-col gap-1">
+                    <span className="font-medium break-words">{note.title}</span>
+                    {note.body === "" ? null : <span className="text-sm break-words whitespace-pre-line">{note.body}</span>}
+                    <time dateTime={note.createdAt} className="text-sm text-muted-foreground">
+                      {dateFormat.format(new Date(note.createdAt))}
+                    </time>
+                  </div>
+                  <Button
+                    variant="outline"
+                    size="sm"
+                    className="self-start"
+                    aria-label={t("admin.notes.deleteNote", { title: note.title })}
+                    onClick={() => {
+                      setDeleting(note);
+                    }}
+                  >
+                    {t("admin.notes.delete")}
+                  </Button>
+                </li>
+              ))}
+            </ul>
+          </CardContent>
+        </Card>
+      ) : null}
+      <ConfirmDialog
+        open={deleting !== null}
+        onOpenChange={(open) => {
+          if (!open) setDeleting(null);
+        }}
+        title={t("admin.notes.confirmTitle")}
+        description={t("admin.notes.confirmDescription", { title: deleting?.title ?? "" })}
+        confirmLabel={t("admin.notes.delete")}
+        destructive
+        fallbackFocus={() => list.current}
+        onConfirm={async () => {
+          if (deleting === null) return;
+          await withStepUp(() => deleteNote(deleting.id));
+          await queryClient.invalidateQueries({ queryKey: ["example", "notes"] });
+        }}
+      />
+    </>
+  );
+}

package/template/modules/example/with-audit/test/example-notes-audit.test.ts

@@ -0,0 +1,22 @@
+import { env } from "cloudflare:workers";
+import { beforeEach, expect, it } from "vitest";
+import { auditLog } from "../src/audit-log.js";
+import { notesCaller, postJson } from "./example-notes-fixtures.js";
+import { migrate } from "./migrate.js";
+
+// EXAMPLE CODE (example module, with audit): adding a note is recorded in the audit trail.
+
+beforeEach(async () => {
+  await migrate();
+});
+
+it("records example.note.created with the note as the subject", async () => {
+  const call = await notesCaller();
+  const response = await call("/v1/example/notes", postJson({ title: "Audited" }));
+  expect(response.status).toBe(201);
+  const { id, authorId } = await response.json<{ id: string; authorId: string | null }>();
+
+  const { items } = await auditLog(env).list({ action: "example.note.created", subjectId: `example_note:${id}` });
+  expect(items).toHaveLength(1);
+  expect(items[0]).toMatchObject({ action: "example.note.created", actorId: authorId });
+});

package/template/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "react-hono-app",
+  "version": "0.0.0",
+  "private": true,
+  "description": "An Inbis app: Hono API and React SPA on one Cloudflare Worker, with D1.",
+  "type": "module",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "dev": "pnpm build:web && wrangler dev",
+    "dev:web": "vite --config web/vite.config.ts",
+    "build": "pnpm build:web && wrangler deploy --dry-run --outdir dist",
+    "build:web": "vite build --config web/vite.config.ts",
+    "typegen": "wrangler types --include-runtime=false --strict-vars=false .wrangler/types/env.d.ts",
+    "typecheck": "tsc && tsc -p web && tsc -p e2e",
+    "lint": "eslint . --max-warnings 0",
+    "test": "vitest run",
+    "test:e2e": "playwright test",
+    "db:migrate": "inbis-db migrate --local",
+    "db:status": "inbis-db status --local"
+  },
+  "dependencies": {
+    "@awsmbiz/inbis-api": "workspace:*",
+    "@awsmbiz/inbis-cloudflare": "workspace:*",
+    "@awsmbiz/inbis-core": "workspace:*",
+    "@awsmbiz/inbis-db": "workspace:*",
+    "@awsmbiz/inbis-ui": "workspace:*",
+    "@hono/zod-openapi": "1.6.3",
+    "drizzle-orm": "0.45.4",
+    "hono": "4.13.14",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "react-hook-form": "7.91.0",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@awsmbiz/inbis-eslint-config": "workspace:*",
+    "@awsmbiz/inbis-tsconfig": "workspace:*",
+    "@axe-core/playwright": "4.14.0",
+    "@cloudflare/vitest-plugin": "1.4.11",
+    "@cloudflare/workers-types": "5.20261030.1",
+    "@playwright/test": "1.64.1",
+    "@tailwindcss/vite": "4.3.3",
+    "@types/node": "24.19.2",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@vitejs/plugin-react": "6.1.2",
+    "eslint": "10.14.0",
+    "tailwindcss": "4.3.3",
+    "typescript": "6.0.3",
+    "vite": "8.3.5",
+    "vitest": "5.0.5",
+    "wrangler": "4.156.0"
+  },
+  "packageManager": "pnpm@12.16.1"
+}

package/template/playwright.config.ts

@@ -0,0 +1,38 @@
+import { defineConfig, devices } from "@playwright/test";
+// inbis:wire playwright.imports
+
+// Browser seam: the Worker + SPA under `wrangler dev`, on a fresh local D1 (its own
+// persist dir) with every migration applied. Port 8790 keeps clear of `pnpm dev` (8787);
+// `E2E_PORT` moves it, and modules' extra servers take the ports after it.
+const PORT = Number(process.env["E2E_PORT"] ?? 8790);
+const BASE_URL = `http://localhost:${PORT}`;
+const STATE = ".wrangler/e2e";
+
+export default defineConfig({
+  testDir: "./e2e",
+  fullyParallel: false,
+  workers: 1,
+  forbidOnly: !!process.env["CI"],
+  retries: process.env["CI"] ? 1 : 0,
+  reporter: process.env["CI"] ? "github" : "list",
+  use: { baseURL: BASE_URL, trace: "retain-on-failure" },
+  projects: [{ name: "chromium", use: { ...devices["Desktop Chrome"] } }],
+  webServer: [
+    {
+      command: [
+        "pnpm build:web",
+        `rm -rf ${STATE}`,
+        `inbis-db migrate --local --persist-to ${STATE}`,
+        // inbis:wire playwright.setup
+        [
+          `wrangler dev --port ${PORT} --persist-to ${STATE}`,
+          // inbis:wire playwright.vars
+        ].join(" "),
+      ].join(" && "),
+      url: `${BASE_URL}/health`,
+      reuseExistingServer: false,
+      timeout: 120_000,
+    },
+    // inbis:wire playwright.servers
+  ],
+});

package/template/renovate.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["config:recommended"],
+  "packageRules": [
+    {
+      "description": "The Inbis platform is released in lockstep: upgrade every package together.",
+      "matchPackageNames": ["@awsmbiz/inbis-*"],
+      "groupName": "Inbis platform",
+      "groupSlug": "inbis-platform"
+    }
+  ]
+}

package/template/src/app.ts

@@ -0,0 +1,46 @@
+import { createApi } from "@awsmbiz/inbis-api";
+import { requireBinding } from "@awsmbiz/inbis-cloudflare";
+import type { Logger } from "@awsmbiz/inbis-core";
+import { createDatabase } from "@awsmbiz/inbis-db";
+import { sql } from "drizzle-orm";
+import { createV1 } from "./v1.js";
+// inbis:wire worker.imports
+
+/** Everything the app injects into the platform packages. Tests can swap these for fakes. */
+export interface AppDeps {
+  /** Base logger; defaults to the console JSON logger (Workers Logs). */
+  logger?: Logger;
+  // inbis:wire worker.deps
+}
+
+/** `TRUSTED_ORIGINS` (comma-separated origins) as a list; throws on an entry that is not an origin. */
+export function trustedOrigins(env: Pick<Env, "TRUSTED_ORIGINS">): string[] {
+  const origins = env.TRUSTED_ORIGINS.split(",")
+    .map((origin) => origin.trim())
+    .filter((origin) => origin !== "");
+  for (const origin of origins) {
+    if (!URL.canParse(origin) || new URL(origin).origin !== origin) {
+      throw new Error(`TRUSTED_ORIGINS: "${origin}" is not an origin (scheme://host[:port], no path).`);
+    }
+  }
+  return origins;
+}
+
+/** Builds the Worker app. `src/index.ts` calls it with the real adapters. */
+export function createApp(deps: AppDeps = {}) {
+  const app = createApi<Env>({
+    info: { title: "React Hono App", version: "0.0.0" },
+    trustedOrigins,
+    readiness: {
+      database: async (c) => {
+        await createDatabase(requireBinding(c.env, "DB")).run(sql`select 1`);
+      },
+    },
+    v1: createV1(),
+    ...(deps.logger === undefined ? {} : { logger: deps.logger }),
+  });
+
+  // inbis:wire worker.routes
+
+  return app;
+}

package/template/src/audit-catalogues.ts

@@ -0,0 +1,9 @@
+// inbis:wire audit.catalogues.imports
+
+/**
+ * Audit action catalogues of the platform packages the app uses (e.g. auth's
+ * `AUTH_AUDIT_ACTIONS`): an audit trail, when the app has one, accepts these action names.
+ */
+export const platformAuditActions: readonly (Readonly<Record<string, string>> | readonly string[])[] = [
+  // inbis:wire audit.catalogues
+];

package/template/src/audit-sink.ts

@@ -0,0 +1,21 @@
+import type { AuditSink, Logger } from "@awsmbiz/inbis-core";
+// inbis:wire audit.imports
+
+/**
+ * Where platform packages (and the app) record audit events. The app has no audit trail
+ * until it adds one (`@awsmbiz/inbis-audit`): until then `auditSinkFor` returns `undefined`
+ * and platform packages fall back to their own behaviour (auth keeps its interim history).
+ */
+export interface AuditSinkOptions {
+  /** The request's logger, for warnings such as an unregistered action. */
+  logger?: Logger | undefined;
+}
+
+const sinks: ((env: Env, options: AuditSinkOptions) => AuditSink)[] = [
+  // inbis:wire audit.sink
+];
+
+/** The app's audit sink for a request, or `undefined` when the app has no audit trail. */
+export function auditSinkFor(env: Env, options: AuditSinkOptions = {}): AuditSink | undefined {
+  return sinks[0]?.(env, options);
+}

package/template/src/env.d.ts

@@ -0,0 +1,21 @@
+// The Worker's bindings, vars and secrets, as declared in wrangler.jsonc. Keep the two in
+// step: when you add a binding or var there, add it here. `pnpm typegen` writes wrangler's
+// own view to .wrangler/types/env.d.ts if you want to compare.
+declare namespace Cloudflare {
+  interface GlobalProps {
+    /** Types `exports` from `cloudflare:workers` (the Worker's own entrypoints). */
+    // eslint-disable-next-line @typescript-eslint/consistent-type-imports -- a global declaration file cannot import
+    mainModule: typeof import("./index");
+  }
+  interface Env {
+    // inbis:wire env.bindings
+    /** The app's own D1 binding (migrations/). */
+    DB: D1Database;
+    /** Comma-separated browser origins allowed to call the API with credentials. */
+    TRUSTED_ORIGINS: string;
+  }
+}
+
+// The global `Env` used in handler types, as `wrangler types` declares it.
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+interface Env extends Cloudflare.Env {}

package/template/src/index.ts

@@ -0,0 +1,18 @@
+import { env } from "cloudflare:workers";
+import { createApp, trustedOrigins, type AppDeps } from "./app.js";
+// inbis:wire index.imports
+
+// Fail at startup, not on the first request, when the configuration is invalid.
+trustedOrigins(env);
+// inbis:wire index.setup
+
+// The real dependencies, built from the environment once per isolate.
+const deps: AppDeps = {
+  // inbis:wire index.deps
+};
+const app = createApp(deps);
+
+export default {
+  fetch: app.fetch,
+  // inbis:wire index.handlers
+} satisfies ExportedHandler<Env>;