minutework 0.1.0

package/assets/templates/next-tenant-app/src/features/shell/components/private-app-shell.tsx

@@ -0,0 +1,624 @@
+"use client";
+
+import type { FormEvent } from "react";
+import { startTransition, useEffect, useEffectEvent, useState } from "react";
+import dynamic from "next/dynamic";
+import Link from "next/link";
+import { useRouter } from "next/navigation";
+import {
+  Building2,
+  KeyRound,
+  LayoutDashboard,
+  Loader2,
+  LogOut,
+  RefreshCcw,
+  ShieldCheck,
+  Workflow,
+} from "lucide-react";
+
+import { TenantDashboard } from "@/features/dashboard/components/tenant-dashboard";
+import { PanelFrame } from "@/design-system/patterns/panel-frame";
+import { StatusBadge } from "@/design-system/patterns/status-badge";
+import { ThemeModeToggle } from "@/design-system/patterns/theme-mode-toggle";
+import { Button } from "@/design-system/primitives/button";
+import { Input } from "@/design-system/primitives/input";
+import { appRoutes } from "@/lib/app-routes";
+import type {
+  AuthenticatedPlatformSession,
+  PasswordStatus,
+  SessionMembership,
+} from "@/lib/platform/contracts";
+
+type ShellView = "dashboard" | "runtime-command-demo";
+
+function RuntimeCommandDemoFallback() {
+  return (
+    <PanelFrame tone="floating" radius="xl" padding="lg" className="space-y-3">
+      <div className="flex items-center gap-2">
+        <Loader2 className="size-4 animate-spin text-primary" />
+        <p className="text-sm font-semibold text-foreground">
+          Loading runtime example
+        </p>
+      </div>
+      <p className="text-sm leading-6 text-muted-foreground">
+        The optional example module is loaded only when the runtime example route
+        is active.
+      </p>
+    </PanelFrame>
+  );
+}
+
+const RuntimeCommandDemo = dynamic(
+  () =>
+    import(
+      "@/features/examples/runtime-command-demo/components/runtime-command-demo"
+    ).then((module) => module.RuntimeCommandDemo),
+  {
+    loading: () => <RuntimeCommandDemoFallback />,
+  },
+);
+
+function membershipById(
+  memberships: SessionMembership[],
+  tenantId: string,
+) {
+  return memberships.find((membership) => membership.tenant_id === tenantId) ?? null;
+}
+
+async function readErrorDetail(response: Response, fallback: string) {
+  const payload = (await response.json().catch(() => null)) as
+    | { detail?: string }
+    | null;
+
+  return payload?.detail || fallback;
+}
+
+export function PrivateAppShell({
+  appName,
+  initialSession,
+  operatorConsoleHref,
+  runtimeCommandExampleEnabled,
+  view,
+}: {
+  appName: string;
+  initialSession: AuthenticatedPlatformSession;
+  operatorConsoleHref?: string;
+  runtimeCommandExampleEnabled: boolean;
+  view: ShellView;
+}) {
+  const router = useRouter();
+  const [session, setSession] = useState(initialSession);
+  const [selectedTenantId, setSelectedTenantId] = useState(
+    initialSession.active_tenant_id,
+  );
+  const [signingOut, setSigningOut] = useState(false);
+  const [tenantPending, setTenantPending] = useState(false);
+  const [tenantError, setTenantError] = useState("");
+  const [tenantNotice, setTenantNotice] = useState("");
+  const [passwordStatus, setPasswordStatus] = useState<PasswordStatus | null>(null);
+  const [passwordLoading, setPasswordLoading] = useState(true);
+  const [passwordPending, setPasswordPending] = useState(false);
+  const [passwordError, setPasswordError] = useState("");
+  const [passwordNotice, setPasswordNotice] = useState("");
+  const [currentPassword, setCurrentPassword] = useState("");
+  const [newPassword, setNewPassword] = useState("");
+  const [confirmPassword, setConfirmPassword] = useState("");
+
+  const activeTenant = session.active_tenant;
+  const activeMembership = membershipById(
+    session.memberships,
+    session.active_tenant_id,
+  );
+  const pendingMembership = membershipById(session.memberships, selectedTenantId);
+
+  function redirectToLogin() {
+    startTransition(() => {
+      router.replace(appRoutes.login);
+      router.refresh();
+    });
+  }
+
+  const loadPasswordStatus = useEffectEvent(async () => {
+    setPasswordLoading(true);
+
+    try {
+      const response = await fetch("/api/auth/password-status", {
+        method: "GET",
+        cache: "no-store",
+      });
+
+      if (response.status === 401) {
+        redirectToLogin();
+        return;
+      }
+
+      if (!response.ok) {
+        setPasswordError(
+          await readErrorDetail(response, "Unable to load password settings."),
+        );
+        return;
+      }
+
+      const payload = (await response.json()) as PasswordStatus;
+      setPasswordStatus(payload);
+      setPasswordError("");
+    } catch {
+      setPasswordError("Unable to load password settings.");
+    } finally {
+      setPasswordLoading(false);
+    }
+  });
+
+  useEffect(() => {
+    setSelectedTenantId(session.active_tenant_id);
+  }, [session.active_tenant_id]);
+
+  useEffect(() => {
+    void loadPasswordStatus();
+  }, []);
+
+  async function handleLogout() {
+    setSigningOut(true);
+    await fetch("/api/auth/logout", { method: "POST" }).catch(() => null);
+    redirectToLogin();
+  }
+
+  async function handleTenantSwitch() {
+    if (!selectedTenantId || selectedTenantId === session.active_tenant_id) {
+      return;
+    }
+
+    setTenantPending(true);
+    setTenantError("");
+    setTenantNotice("");
+
+    try {
+      const response = await fetch("/api/auth/context", {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ tenant_id: selectedTenantId }),
+      });
+
+      if (response.status === 401) {
+        redirectToLogin();
+        return;
+      }
+
+      if (!response.ok) {
+        setTenantError(
+          await readErrorDetail(response, "Unable to update tenant context."),
+        );
+        return;
+      }
+
+      const payload = (await response.json()) as AuthenticatedPlatformSession;
+      setSession(payload);
+      setTenantNotice("Tenant context updated.");
+    } catch {
+      setTenantError("Unable to update tenant context.");
+    } finally {
+      setTenantPending(false);
+    }
+  }
+
+  async function handleTenantReset() {
+    setTenantPending(true);
+    setTenantError("");
+    setTenantNotice("");
+
+    try {
+      const response = await fetch("/api/auth/context", {
+        method: "DELETE",
+      });
+
+      if (response.status === 401) {
+        redirectToLogin();
+        return;
+      }
+
+      if (!response.ok) {
+        setTenantError(
+          await readErrorDetail(response, "Unable to reset tenant context."),
+        );
+        return;
+      }
+
+      const payload = (await response.json()) as AuthenticatedPlatformSession;
+      setSession(payload);
+      setTenantNotice("Tenant context reset to the platform default.");
+    } catch {
+      setTenantError("Unable to reset tenant context.");
+    } finally {
+      setTenantPending(false);
+    }
+  }
+
+  async function handlePasswordSubmit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+
+    if (newPassword !== confirmPassword) {
+      setPasswordError("Passwords must match.");
+      return;
+    }
+
+    setPasswordPending(true);
+    setPasswordError("");
+    setPasswordNotice("");
+
+    try {
+      const response = await fetch("/api/auth/password-change", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          current_password: currentPassword,
+          new_password: newPassword,
+          confirm_password: confirmPassword,
+        }),
+      });
+
+      if (response.status === 401) {
+        redirectToLogin();
+        return;
+      }
+
+      if (!response.ok) {
+        setPasswordError(
+          await readErrorDetail(response, "Unable to change password."),
+        );
+        return;
+      }
+
+      const payload = (await response.json()) as PasswordStatus;
+      setPasswordStatus(payload);
+      setCurrentPassword("");
+      setNewPassword("");
+      setConfirmPassword("");
+      setPasswordNotice("Password saved.");
+    } catch {
+      setPasswordError("Unable to change password.");
+    } finally {
+      setPasswordPending(false);
+    }
+  }
+
+  if (!activeTenant) {
+    return (
+      <main className="min-h-screen bg-background text-foreground">
+        <div className="mx-auto flex min-h-screen max-w-5xl items-center px-6 py-10">
+          <PanelFrame tone="floating" radius="xl" padding="lg" className="w-full space-y-4">
+            <div className="space-y-2">
+              <p className="text-sm font-semibold uppercase tracking-widest text-muted-foreground">
+                Missing tenant context
+              </p>
+              <h1 className="text-3xl font-semibold tracking-tight">
+                This account is authenticated but has no active tenant membership.
+              </h1>
+              <p className="text-sm leading-7 text-muted-foreground">
+                The template expects an authenticated membership-backed tenant
+                session before entering the private app shell.
+              </p>
+            </div>
+            <Button onClick={handleLogout} variant="outline" className="w-fit">
+              Return to login
+            </Button>
+          </PanelFrame>
+        </div>
+      </main>
+    );
+  }
+
+  const content =
+    view === "runtime-command-demo" ? (
+      <RuntimeCommandDemo
+        activeTenant={activeTenant}
+        onUnauthorized={redirectToLogin}
+        viewerName={session.user.username}
+      />
+    ) : (
+      <TenantDashboard
+        appName={appName}
+        runtimeCommandExampleEnabled={runtimeCommandExampleEnabled}
+        session={session}
+      />
+    );
+
+  return (
+    <main className="min-h-screen bg-background text-foreground">
+      <div className="mx-auto flex min-h-screen max-w-7xl flex-col gap-6 px-6 py-8">
+        <header className="flex flex-col gap-6 xl:flex-row xl:items-start xl:justify-between">
+          <div className="space-y-4">
+            <div className="space-y-2">
+              <p className="text-sm font-semibold uppercase tracking-widest text-muted-foreground">
+                Private Next.js Tenant Template
+              </p>
+              <h1 className="max-w-3xl text-4xl font-semibold tracking-tight text-balance sm:text-5xl">
+                {appName}
+              </h1>
+              <p className="max-w-3xl text-base leading-7 text-muted-foreground sm:text-lg">
+                A canonical `platform_session_bff` scaffold for tenant-facing
+                Builder apps. The browser talks only to this Next.js app, and the
+                app keeps platform auth and CSRF credentials server-owned.
+              </p>
+            </div>
+
+            <div className="flex flex-wrap gap-3">
+              <StatusBadge tone="primary">platform_session_bff</StatusBadge>
+              <StatusBadge tone="info">Active tenant aware</StatusBadge>
+              <StatusBadge tone="success">Builder-ready scaffold</StatusBadge>
+            </div>
+          </div>
+
+          <div className="flex flex-col gap-3 sm:flex-row sm:items-start">
+            <ThemeModeToggle className="w-full sm:w-72" />
+            {operatorConsoleHref ? (
+              <Button asChild type="button" variant="outline">
+                <a href={operatorConsoleHref} target="_blank" rel="noreferrer">
+                  Open /ops
+                </a>
+              </Button>
+            ) : null}
+            <Button
+              type="button"
+              variant="outline"
+              className="gap-2"
+              onClick={handleLogout}
+              disabled={signingOut}
+            >
+              {signingOut ? (
+                <Loader2 className="size-4 animate-spin" />
+              ) : (
+                <LogOut className="size-4" />
+              )}
+              {signingOut ? "Signing out" : "Log out"}
+            </Button>
+          </div>
+        </header>
+
+        <nav className="flex flex-wrap gap-2">
+          <Button asChild variant={view === "dashboard" ? "default" : "outline"}>
+            <Link href={appRoutes.appHome}>
+              <LayoutDashboard className="size-4" />
+              Dashboard
+            </Link>
+          </Button>
+          {runtimeCommandExampleEnabled ? (
+            <Button
+              asChild
+              variant={view === "runtime-command-demo" ? "default" : "outline"}
+            >
+              <Link href={appRoutes.runtimeCommandExample}>
+                <Workflow className="size-4" />
+                Runtime example
+              </Link>
+            </Button>
+          ) : null}
+        </nav>
+
+        <section className="grid gap-6 xl:grid-cols-[1.2fr,0.8fr]">
+          <div>{content}</div>
+
+          <div className="grid gap-6">
+            <PanelFrame tone="floating" radius="xl" padding="lg" className="space-y-5">
+              <div className="space-y-2">
+                <div className="flex items-center gap-2">
+                  <Building2 className="size-4 text-primary" />
+                  <p className="text-sm font-semibold uppercase tracking-widest text-muted-foreground">
+                    Tenant context
+                  </p>
+                </div>
+                <h2 className="text-2xl font-semibold tracking-tight">
+                  {activeTenant.tenant_name}
+                </h2>
+                <p className="text-sm leading-6 text-muted-foreground">
+                  Signed in as{" "}
+                  <span className="font-medium text-foreground">
+                    {session.user.username}
+                  </span>{" "}
+                  with role{" "}
+                  <span className="font-medium text-foreground">
+                    {activeMembership?.role ?? activeTenant.role}
+                  </span>
+                  .
+                </p>
+              </div>
+
+              <div className="space-y-2">
+                <label
+                  className="text-xs font-semibold uppercase tracking-widest text-muted-foreground"
+                  htmlFor="tenant-context"
+                >
+                  Active tenant
+                </label>
+                <select
+                  id="tenant-context"
+                  className="flex h-12 w-full rounded-xl border border-border bg-background px-4 text-sm text-foreground outline-none transition-colors focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring/40"
+                  value={selectedTenantId}
+                  onChange={(event) => {
+                    setSelectedTenantId(event.target.value);
+                    setTenantError("");
+                    setTenantNotice("");
+                  }}
+                  disabled={tenantPending}
+                >
+                  {session.memberships.map((membership) => (
+                    <option key={membership.tenant_id} value={membership.tenant_id}>
+                      {membership.tenant_name} ({membership.tenant_slug})
+                    </option>
+                  ))}
+                </select>
+              </div>
+
+              {pendingMembership ? (
+                <PanelFrame tone="raised" radius="xl" padding="md" className="space-y-2">
+                  <p className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+                    Selected membership
+                  </p>
+                  <p className="text-sm font-semibold text-foreground">
+                    {pendingMembership.tenant_name}
+                  </p>
+                  <p className="text-sm text-muted-foreground">
+                    {pendingMembership.tenant_slug} · {pendingMembership.role}
+                  </p>
+                </PanelFrame>
+              ) : null}
+
+              <div className="flex flex-wrap gap-3">
+                <Button
+                  type="button"
+                  className="gap-2"
+                  onClick={handleTenantSwitch}
+                  disabled={tenantPending || selectedTenantId === session.active_tenant_id}
+                >
+                  {tenantPending ? (
+                    <Loader2 className="size-4 animate-spin" />
+                  ) : (
+                    <Building2 className="size-4" />
+                  )}
+                  Apply tenant
+                </Button>
+                <Button
+                  type="button"
+                  variant="outline"
+                  className="gap-2"
+                  onClick={handleTenantReset}
+                  disabled={tenantPending}
+                >
+                  <RefreshCcw className="size-4" />
+                  Reset context
+                </Button>
+              </div>
+
+              {tenantError ? <p className="text-sm text-destructive">{tenantError}</p> : null}
+              {tenantNotice ? <p className="text-sm text-primary">{tenantNotice}</p> : null}
+            </PanelFrame>
+
+            <PanelFrame tone="floating" radius="xl" padding="lg" className="space-y-5">
+              <div className="space-y-2">
+                <div className="flex items-center gap-2">
+                  <ShieldCheck className="size-4 text-primary" />
+                  <p className="text-sm font-semibold uppercase tracking-widest text-muted-foreground">
+                    Password settings
+                  </p>
+                </div>
+                <h2 className="text-2xl font-semibold tracking-tight">
+                  Account security
+                </h2>
+                <p className="text-sm leading-6 text-muted-foreground">
+                  Password status and updates are proxied through the same
+                  server-owned BFF as login, logout, and session restore.
+                </p>
+              </div>
+
+              {passwordLoading ? (
+                <PanelFrame tone="raised" radius="xl" padding="lg" className="space-y-2">
+                  <div className="flex items-center gap-2">
+                    <Loader2 className="size-4 animate-spin text-primary" />
+                    <p className="text-sm font-semibold text-foreground">
+                      Loading password status
+                    </p>
+                  </div>
+                </PanelFrame>
+              ) : (
+                <form className="space-y-4" onSubmit={handlePasswordSubmit}>
+                  <div className="flex flex-wrap gap-3">
+                    <StatusBadge tone={passwordStatus?.has_password ? "success" : "info"}>
+                      {passwordStatus?.has_password
+                        ? "Password enabled"
+                        : "Password missing"}
+                    </StatusBadge>
+                    <StatusBadge tone="default">Platform session</StatusBadge>
+                  </div>
+
+                  {passwordStatus?.has_password ? (
+                    <div className="space-y-2">
+                      <label
+                        className="text-xs font-semibold uppercase tracking-widest text-muted-foreground"
+                        htmlFor="current-password"
+                      >
+                        Current password
+                      </label>
+                      <Input
+                        id="current-password"
+                        type="password"
+                        autoComplete="current-password"
+                        className="h-12"
+                        value={currentPassword}
+                        onChange={(event) => {
+                          setCurrentPassword(event.target.value);
+                          setPasswordError("");
+                          setPasswordNotice("");
+                        }}
+                      />
+                    </div>
+                  ) : null}
+
+                  <div className="space-y-2">
+                    <label
+                      className="text-xs font-semibold uppercase tracking-widest text-muted-foreground"
+                      htmlFor="new-password"
+                    >
+                      New password
+                    </label>
+                    <Input
+                      id="new-password"
+                      type="password"
+                      autoComplete="new-password"
+                      className="h-12"
+                      value={newPassword}
+                      onChange={(event) => {
+                        setNewPassword(event.target.value);
+                        setPasswordError("");
+                        setPasswordNotice("");
+                      }}
+                    />
+                  </div>
+
+                  <div className="space-y-2">
+                    <label
+                      className="text-xs font-semibold uppercase tracking-widest text-muted-foreground"
+                      htmlFor="confirm-password"
+                    >
+                      Confirm password
+                    </label>
+                    <Input
+                      id="confirm-password"
+                      type="password"
+                      autoComplete="new-password"
+                      className="h-12"
+                      value={confirmPassword}
+                      onChange={(event) => {
+                        setConfirmPassword(event.target.value);
+                        setPasswordError("");
+                        setPasswordNotice("");
+                      }}
+                    />
+                  </div>
+
+                  {passwordError ? (
+                    <p className="text-sm text-destructive">{passwordError}</p>
+                  ) : null}
+                  {passwordNotice ? (
+                    <p className="text-sm text-primary">{passwordNotice}</p>
+                  ) : null}
+
+                  <Button
+                    type="submit"
+                    className="gap-2"
+                    disabled={passwordPending || passwordLoading}
+                  >
+                    {passwordPending ? (
+                      <Loader2 className="size-4 animate-spin" />
+                    ) : (
+                      <KeyRound className="size-4" />
+                    )}
+                    {passwordStatus?.has_password ? "Update password" : "Create password"}
+                  </Button>
+                </form>
+              )}
+            </PanelFrame>
+          </div>
+        </section>
+      </div>
+    </main>
+  );
+}

package/assets/templates/next-tenant-app/src/lib/app-routes.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+
+import { appRoutes } from "@/lib/app-routes";
+
+describe("appRoutes", () => {
+  it("builds a blog route from a single slug segment", () => {
+    expect(appRoutes.blogPost("launching-the-combined-web-starter")).toBe(
+      "/blog/launching-the-combined-web-starter",
+    );
+    expect(appRoutes.blogPost(["launching-the-combined-web-starter"])).toBe(
+      "/blog/launching-the-combined-web-starter",
+    );
+  });
+
+  it("rejects multi-segment blog slugs instead of truncating them", () => {
+    expect(() => appRoutes.blogPost(["release", "v1"])).toThrow(
+      "Blog routes require exactly one slug segment.",
+    );
+  });
+});

package/assets/templates/next-tenant-app/src/lib/app-routes.ts

@@ -0,0 +1,59 @@
+import type { Route } from "next";
+
+function joinRouteSegments(segments: readonly string[]) {
+  return segments.map((segment) => encodeURIComponent(segment)).join("/");
+}
+
+function requireSingleRouteSegment(
+  slug: string | readonly string[],
+  routeLabel: string,
+) {
+  if (typeof slug === "string") {
+    const segment = slug.trim();
+
+    if (segment.length === 0) {
+      throw new Error(`${routeLabel} require a non-empty slug segment.`);
+    }
+
+    return segment;
+  }
+
+  if (slug.length !== 1) {
+    throw new Error(`${routeLabel} require exactly one slug segment.`);
+  }
+
+  const [segment] = slug;
+  const normalizedSegment = segment?.trim();
+
+  if (!normalizedSegment) {
+    throw new Error(`${routeLabel} require a non-empty slug segment.`);
+  }
+
+  return normalizedSegment;
+}
+
+const publicHomeRoute: Route = "/";
+const pricingRoute: Route = "/pricing";
+const docsIndexRoute: Route = "/docs";
+const blogIndexRoute: Route = "/blog";
+const loginRoute: Route = "/login";
+const appHomeRoute: Route = "/app";
+const runtimeCommandExampleRoute: Route = "/app/examples/runtime-commands";
+
+export const appRoutes = {
+  publicHome: publicHomeRoute,
+  pricing: pricingRoute,
+  docsIndex: docsIndexRoute,
+  docsPage(slugParts: readonly string[]) {
+    return `/docs/${joinRouteSegments(slugParts)}` as Route;
+  },
+  blogIndex: blogIndexRoute,
+  blogPost(slug: string | readonly string[]) {
+    return `/blog/${encodeURIComponent(
+      requireSingleRouteSegment(slug, "Blog routes"),
+    )}` as Route;
+  },
+  login: loginRoute,
+  appHome: appHomeRoute,
+  runtimeCommandExample: runtimeCommandExampleRoute,
+};