@podosoft/podokit 1.6.1 → 1.6.2

package/dist/deploy-checks.d.ts

@@ -24,7 +24,10 @@ export interface ConnectionBudget {
     perProcessTerms: string[];
     steadyProcesses: number;
     steady: number;
-    /** Processes and connections while a rollout runs old and new pods side by side. */
+    /**
+     * Processes and connections while a rollout runs old and new pods side by side,
+     * counting replaced pods that still hold their pools while they terminate.
+     */
     rolloutProcesses: number;
     rollout: number;
     migration: number;
@@ -32,10 +35,18 @@ export interface ConnectionBudget {
 }
 /**
  * The most PostgreSQL connections the deployment can open: every API and worker
- * process with each pool full, the Kubernetes rollout's surge pod per workload
- * (the rendered strategy allows one), and the migration that runs beside the
- * release still serving. Compose replaces containers without a surge. Null when
- * the deployment uses no PostgreSQL.
+ * process with each pool full, a Kubernetes rollout's old and new pods together,
+ * and the migration that runs beside the release still serving. Null when the
+ * deployment uses no PostgreSQL.
+ *
+ * A replaced pod keeps its pools until its process exits, up to its grace period
+ * after the scale-down (the preStop sleep plus the drain for API pods), and the
+ * Deployment controller does not count terminating pods against maxSurge: it
+ * starts the next surge pod as soon as the previous replacement is ready. When
+ * replacements become ready faster than replaced pods exit, every old pod of a
+ * workload can still hold its pools while all of its new pods run, twice its
+ * replicas whatever the surge. Compose stops a container before it starts the
+ * replacement, so it never runs both.
  */
 export declare function connectionBudget(profile: AnyDeployProfile, modules: Set<string>): ConnectionBudget | null;
 /** The plan warning for a budget over the limit, or null. */

package/dist/deploy-checks.js

@@ -104,10 +104,18 @@ function poolSize(runtimeConfig, key, fallback) {
 }
 /**
  * The most PostgreSQL connections the deployment can open: every API and worker
- * process with each pool full, the Kubernetes rollout's surge pod per workload
- * (the rendered strategy allows one), and the migration that runs beside the
- * release still serving. Compose replaces containers without a surge. Null when
- * the deployment uses no PostgreSQL.
+ * process with each pool full, a Kubernetes rollout's old and new pods together,
+ * and the migration that runs beside the release still serving. Null when the
+ * deployment uses no PostgreSQL.
+ *
+ * A replaced pod keeps its pools until its process exits, up to its grace period
+ * after the scale-down (the preStop sleep plus the drain for API pods), and the
+ * Deployment controller does not count terminating pods against maxSurge: it
+ * starts the next surge pod as soon as the previous replacement is ready. When
+ * replacements become ready faster than replaced pods exit, every old pod of a
+ * workload can still hold its pools while all of its new pods run, twice its
+ * replicas whatever the surge. Compose stops a container before it starts the
+ * replacement, so it never runs both.
  */
 function connectionBudget(profile, modules) {
     const postgres = profile.dependencies.postgres;
@@ -130,7 +138,7 @@ function connectionBudget(profile, modules) {
     }
     const worker = profile.workloads.worker;
     const steadyProcesses = profile.workloads.api.replicas + (worker?.replicas ?? 0);
-    const rolloutProcesses = steadyProcesses + (profile.driver === "kubernetes-helm" ? 1 + (worker ? 1 : 0) : 0);
+    const rolloutProcesses = profile.driver === "kubernetes-helm" ? 2 * steadyProcesses : steadyProcesses;
     const maxConnections = postgres.maxConnections ?? exports.DEFAULT_MAX_CONNECTIONS;
     const steady = steadyProcesses * perProcess;
     const rollout = rolloutProcesses * perProcess;
@@ -151,7 +159,7 @@ function budgetSummary(budget) {
     return (`each API or worker process holds up to ${budget.perProcess} (${budget.perProcessTerms.join(" + ")}); ` +
         `${budget.steadyProcesses} process(es) hold ${budget.steady}` +
         (budget.rolloutProcesses > budget.steadyProcesses
-            ? `, ${budget.rolloutProcesses} during a rollout hold ${budget.rollout}`
+            ? `, ${budget.rolloutProcesses} during a rollout, counting replaced pods that have not exited, hold ${budget.rollout}`
             : "") +
         `, and the migration adds ${budget.migration} to the ${budget.steady}`);
 }

package/dist/deploy-render.js

@@ -396,7 +396,27 @@ ${entries.length ? `data:\n${entries.map(([key, value]) => `  ${key}: ${quote(va
 // of 1 s: above the API's 800 ms per-check readiness bound, and enough for a busy
 // web server.
 const PROBE_TIMEOUT_SECONDS = 2;
-function deployment(profile, kind, workload, image, rolloutStateDigest, runtimeConfigDigest) {
+// A terminating pod still receives new connections until every node and the
+// ingress controller drop it from the Service's endpoints, while the API and web
+// servers stop accepting them on SIGTERM. The kubelet runs this sleep before it
+// sends SIGTERM, so the pod keeps serving meanwhile. PodoKit's API and web images
+// are Alpine-based and ship /bin/sleep; an exec hook works on every Kubernetes
+// version, unlike the sleep action.
+const PRE_STOP_SLEEP_SECONDS = 5;
+// The web server drains for SHUTDOWN_TIMEOUT seconds (30 unless set) and then
+// force-closes for up to one more. The API's stop waits for in-flight requests
+// without a bound of its own, so it gets the same window, which covers the /api
+// proxy's default 30 s wait. The grace period also counts the preStop sleep.
+const DEFAULT_SHUTDOWN_TIMEOUT_SECONDS = 30;
+const SHUTDOWN_MARGIN_SECONDS = 5;
+function terminationGracePeriodSeconds(runtimeConfig) {
+    const configured = runtimeConfig.SHUTDOWN_TIMEOUT;
+    const drain = configured !== undefined && /^\d+$/.test(configured)
+        ? Number(configured)
+        : DEFAULT_SHUTDOWN_TIMEOUT_SECONDS;
+    return PRE_STOP_SLEEP_SECONDS + drain + SHUTDOWN_MARGIN_SECONDS;
+}
+function deployment(profile, kind, workload, image, rolloutStateDigest, runtimeConfigDigest, gracePeriodSeconds) {
     const name = `${profile.target.release}-${kind}`;
     const workloadSecret = kind === "api" ? profile.secrets.api : profile.secrets.web;
     const secretEnvFrom = workloadSecret
@@ -456,6 +476,7 @@ ${labels(name, 8)}    spec:
         runAsUser: 100
         runAsGroup: 101
         seccompProfile: { type: RuntimeDefault }
+      terminationGracePeriodSeconds: ${gracePeriodSeconds}
       containers:
         - name: ${kind}
           image: ${quote(image)}
@@ -467,6 +488,9 @@ ${labels(name, 8)}    spec:
             - configMapRef: { name: ${profile.target.release}-runtime }
 ${secretEnvFrom}          ports:
             - { name: http, containerPort: 3000 }
+          lifecycle:
+            preStop:
+              exec: { command: [sleep, "${PRE_STOP_SLEEP_SECONDS}"] }
 ${probe}${resources(workload.resources)}---
 apiVersion: v1
 kind: Service
@@ -634,10 +658,11 @@ ${apiPathIngress(profile, tls)}`;
 }
 function applicationManifest(profile, images, rolloutStateDigest, workerCommand, runtimeConfig) {
     const runtimeConfigDigest = digest(["runtime-config", JSON.stringify(sortedRuntimeConfig(runtimeConfig))]);
+    const gracePeriodSeconds = terminationGracePeriodSeconds(runtimeConfig);
     return [
         configMap(profile, runtimeConfig),
-        deployment(profile, "api", profile.workloads.api, images.api, rolloutStateDigest, runtimeConfigDigest),
-        deployment(profile, "web", profile.workloads.web, images.web, rolloutStateDigest, runtimeConfigDigest),
+        deployment(profile, "api", profile.workloads.api, images.api, rolloutStateDigest, runtimeConfigDigest, gracePeriodSeconds),
+        deployment(profile, "web", profile.workloads.web, images.web, rolloutStateDigest, runtimeConfigDigest, gracePeriodSeconds),
         workerDeployment(profile, images.api, rolloutStateDigest, runtimeConfigDigest, workerCommand),
         disruptionBudget(profile, "api"),
         disruptionBudget(profile, "web"),

package/dist/deploy.d.ts

@@ -38,7 +38,16 @@ export interface DeploymentStatus {
         readyReplicas: number;
         replicas: number;
         images: string[];
+        /** Container restarts of the running pods of the Deployment's current revision. */
         restartCount: number;
+        /**
+         * Pods still listed that are not current: from an earlier revision, or
+         * terminating. They linger for the termination grace period after a rollout.
+         */
+        previousPods: {
+            count: number;
+            restartCount: number;
+        };
     }>;
 }
 export interface VerificationResult {

package/dist/deploy.js

@@ -423,15 +423,86 @@ function parseDeployment(output, workloadName) {
     }
     return deployment;
 }
-function restartCount(output, workloadName) {
-    const values = output
-        .split(/\s+/)
-        .map((value) => value.trim())
-        .filter(Boolean);
-    if (values.some((value) => !/^(0|[1-9][0-9]*)$/.test(value))) {
-        throw new Error(`Kubernetes pod restart counts for ${workloadName} are invalid.`);
+const REVISION_ANNOTATION = "deployment.kubernetes.io/revision";
+const POD_TEMPLATE_HASH_LABEL = "pod-template-hash";
+function deploymentRevision(deployment, workloadName) {
+    const revision = deployment.metadata?.annotations?.[REVISION_ANNOTATION];
+    if (typeof revision !== "string" || !/^[1-9][0-9]*$/.test(revision)) {
+        throw new Error(`Kubernetes Deployment ${workloadName} has no valid ${REVISION_ANNOTATION} annotation.`);
     }
-    return values.reduce((sum, value) => sum + Number(value), 0);
+    return revision;
+}
+function kubernetesListItems(output, description) {
+    const list = parseJson(output, description);
+    if (!isRecord(list) || !Array.isArray(list.items)) {
+        throw new Error(`${description} returned an invalid list.`);
+    }
+    return list.items;
+}
+function optionalRecord(value) {
+    return value === undefined || isRecord(value);
+}
+/** The pod-template-hash of the ReplicaSet that carries the Deployment's revision. */
+function currentPodTemplateHash(output, workloadName, revision) {
+    const description = `Kubernetes ReplicaSets of ${workloadName}`;
+    const matching = kubernetesListItems(output, description).map((item) => {
+        if (!isRecord(item) ||
+            !isRecord(item.metadata) ||
+            !optionalRecord(item.metadata.annotations) ||
+            !optionalRecord(item.metadata.labels)) {
+            throw new Error(`${description} have an invalid schema.`);
+        }
+        return {
+            revision: item.metadata.annotations?.[REVISION_ANNOTATION],
+            hash: item.metadata.labels?.[POD_TEMPLATE_HASH_LABEL],
+        };
+    }).filter((replicaSet) => replicaSet.revision === revision);
+    if (matching.length !== 1) {
+        throw new Error(`Kubernetes Deployment ${workloadName} has ${matching.length} ReplicaSets for revision ${revision}; expected one.`);
+    }
+    const hash = matching[0].hash;
+    if (typeof hash !== "string" || hash.length === 0) {
+        throw new Error(`${description}: revision ${revision} has no ${POD_TEMPLATE_HASH_LABEL} label.`);
+    }
+    return hash;
+}
+/**
+ * Restarts of the current revision's running pods, and of the rest separately.
+ * Pods of every revision share the workload label, and an earlier ReplicaSet's
+ * pods stay listed with a deletionTimestamp until they finish terminating.
+ */
+function podRestarts(output, workloadName, currentHash) {
+    const description = `Kubernetes pods of ${workloadName}`;
+    const result = { restartCount: 0, previousPods: { count: 0, restartCount: 0 } };
+    for (const pod of kubernetesListItems(output, description)) {
+        if (!isRecord(pod) ||
+            !isRecord(pod.metadata) ||
+            !optionalRecord(pod.metadata.labels) ||
+            (pod.status !== undefined && !isRecord(pod.status))) {
+            throw new Error(`${description} have an invalid schema.`);
+        }
+        // A pod that has not started a container yet reports no statuses.
+        const statuses = pod.status?.containerStatuses ?? [];
+        if (!Array.isArray(statuses))
+            throw new Error(`${description} have an invalid schema.`);
+        let restarts = 0;
+        for (const status of statuses) {
+            const count = isRecord(status) ? status.restartCount : undefined;
+            if (typeof count !== "number" || !Number.isInteger(count) || count < 0) {
+                throw new Error(`Kubernetes pod restart counts for ${workloadName} are invalid.`);
+            }
+            restarts += count;
+        }
+        const terminating = pod.metadata.deletionTimestamp !== undefined && pod.metadata.deletionTimestamp !== null;
+        if (!terminating && pod.metadata.labels?.[POD_TEMPLATE_HASH_LABEL] === currentHash) {
+            result.restartCount += restarts;
+        }
+        else {
+            result.previousPods.count += 1;
+            result.previousPods.restartCount += restarts;
+        }
+    }
+    return result;
 }
 function planDigest(input, runtime) {
     return (0, node_crypto_1.createHash)("sha256")
@@ -867,14 +938,9 @@ function getDeploymentStatus(projectRoot, profileName, runner = defaultRunner) {
     });
     const deployments = items.map((item) => {
         const name = item.metadata.name;
-        const observedRestartCount = restartCount(checked(runner, "kubectl", kubectlArgs(profile, [
-            "get",
-            "pods",
-            "-l",
-            `app.kubernetes.io/name=${name}`,
-            "-o",
-            "jsonpath={range .items[*].status.containerStatuses[*]}{.restartCount}{\"\\n\"}{end}",
-        ])), name);
+        const selector = `app.kubernetes.io/name=${name}`;
+        const currentHash = currentPodTemplateHash(checked(runner, "kubectl", kubectlArgs(profile, ["get", "replicasets", "-l", selector, "-o", "json"])), name, deploymentRevision(item, name));
+        const restarts = podRestarts(checked(runner, "kubectl", kubectlArgs(profile, ["get", "pods", "-l", selector, "-o", "json"])), name, currentHash);
         return {
             name,
             readyReplicas: item.status?.readyReplicas ?? 0,
@@ -882,7 +948,7 @@ function getDeploymentStatus(projectRoot, profileName, runner = defaultRunner) {
             images: (item.spec?.template?.spec?.containers ?? [])
                 .map((container) => container.image)
                 .filter((image) => typeof image === "string"),
-            restartCount: observedRestartCount,
+            ...restarts,
         };
     });
     return {

package/dist/index.js

@@ -716,7 +716,8 @@ async function main(argv) {
                 }
                 process.stdout.write(`Applied: ${result.written.length} written, ${result.moved.length} moved, ` +
                     `${result.removed.length} removed, ` +
-                    `${result.merged.length} merged, ${result.conflicts.length} conflict.\n`);
+                    `${result.merged.length} merged, ${result.conflicts.length} conflict, ` +
+                    `${result.skipped.length} skipped.\n`);
                 writeApiPaths("Direct API paths:", result.apiPaths, "add");
                 if (result.conflicts.length) {
                     process.stdout.write("\nResolve the following, then commit:\n" +
@@ -729,6 +730,11 @@ async function main(argv) {
                         result.review.map((f) => `  ${f}`).join("\n") +
                         "\n");
                 }
+                if (result.skipped.length) {
+                    process.stdout.write("\nSkipped edited files, left as they are:\n" +
+                        result.skipped.map((file) => `  ${file.path}  (${file.reason})`).join("\n") +
+                        "\n");
+                }
                 return;
             }
             const plan = (0, update_1.planUpdate)(process.cwd(), templatesDir);
@@ -759,7 +765,8 @@ async function main(argv) {
                 }
                 process.stdout.write(`${shown.length ? "\n" : ""}${counts.update} update, ${counts.add} add, ${counts.move} move, ` +
                     `${counts.remove} remove, ${counts.conflict} conflict, ${counts.review} review. ` +
-                    `Dry-run — nothing was written. Re-run with --apply to write (use --from <dir> for a 3-way merge).\n`);
+                    `Dry-run — nothing was written. Re-run with --apply to write; it 3-way merges each conflict ` +
+                    `against the ${plan.fromVersion} templates, fetched from npm unless --from <dir> gives them.\n`);
             }
             writeOwnedTemplateNotes(plan, templatesDir, args.from);
         }

package/dist/templates/fullstack/dot-agents/skills/podokit-deploy/SKILL.md

@@ -22,7 +22,7 @@ Read the profile's `driver` first and say which one you are operating.
 7. Do not apply until the user explicitly approves that exact plan.
 8. Apply with `{{packageExecutor}} @podosoft/podokit deploy apply --profile <name> --release <stable-semver> --confirm <plan-hash>`.
 9. Run `{{packageExecutor}} @podosoft/podokit deploy status --profile <name> --json` and `{{packageExecutor}} @podosoft/podokit deploy verify --profile <name> --json`.
-10. Report the exact images, the revision, running replicas, restart totals, and the verification result. Report `syncDrift` too: a non-empty value means containers are running locally synced artifacts and the release tag does not describe what is serving.
+10. Report the exact images, the revision, running replicas, restart counts, and the verification result. On Kubernetes, each Deployment's `restartCount` covers only the running pods of its current revision, and `previousPods` gives the `count` and `restartCount` of the pods still listed from an earlier revision or terminating. Right after `apply` or `rollback` these are usually the replaced pods finishing their grace period: report them separately and never attribute their restarts to the new release. Report `syncDrift` too: a non-empty value means containers are running locally synced artifacts and the release tag does not describe what is serving.
 
 ## Iterating against a deployment is a different command
 

package/dist/templates/fullstack/dot-agents/skills/podokit-deploy/references/profile.md

@@ -34,7 +34,9 @@ Review these fields before planning:
   PostgreSQL also takes `maxConnections` (default 100) and `appPools` for pools the
   application opens itself, each sized by a `runtimeConfig` key (`sizeKey`) or a
   fixed `size` when the code sets it; the doctor and the plan check the connection budget
-  against them, so lower `DB_POOL_MAX`/`DB_AUTH_POOL_MAX` or replicas when they warn.
+  against them, counting every API and worker replica twice during a Kubernetes rollout
+  because replaced pods keep their pools until they exit, so lower
+  `DB_POOL_MAX`/`DB_AUTH_POOL_MAX` or replicas when they warn.
 - `secrets`: API/optional web Secret names and required key names, plus image-pull Secret
 - `runtimeConfig`: non-sensitive environment values only
 - `verification`: HTTPS origin and checks with exact statuses and optional JSON fields

package/dist/templates/fullstack/tests/helpers/paths.ts

@@ -20,9 +20,15 @@ export interface AppPaths {
    * `AccountMenu` for a signed-in user, or null when none does.
    */
   accountMenu: string | null;
+  /**
+   * A page that renders the managed `ThemeToggle` for the signed-in
+   * administrator, or null when none does. Defaults to `accountMenu`, and to
+   * the admin console, whose header renders the toggle, when that is null.
+   */
+  themeToggle: string | null;
 }
 
-const defaults: AppPaths = {
+const defaults: Omit<AppPaths, "themeToggle"> = {
   home: "/",
   homeReady: (page) => page.getByRole("heading", { level: 1 }),
   indexable: ["/"],
@@ -30,4 +36,9 @@ const defaults: AppPaths = {
   accountMenu: "/",
 };
 
-export const paths: AppPaths = { ...defaults, ...appPaths };
+const merged = { ...defaults, ...appPaths };
+
+export const paths: AppPaths = {
+  ...merged,
+  themeToggle: appPaths.themeToggle === undefined ? (merged.accountMenu ?? "/admin") : appPaths.themeToggle,
+};

package/dist/templates/modules/admin-dashboard/files/tests/api/audit.api.spec.ts

@@ -1,10 +1,21 @@
+import type { APIRequestContext } from "@playwright/test";
 import { expect, test } from "../helpers/disposable-users";
 import { ADMIN, USER } from "../helpers/accounts";
+import { mailpitReachable, waitForOtp } from "../helpers/mailpit";
+import { totpCode } from "../helpers/totp";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 const origin = { origin: base };
+const PASSWORD = "Podokit3e-Str0ng!pw";
 
-type Entry = { id: string; action: string; actorEmail: string | null; targetLabel: string | null; createdAt: string };
+type Entry = {
+  id: string;
+  action: string;
+  actorEmail: string | null;
+  targetLabel: string | null;
+  metadata: Record<string, unknown> | null;
+  createdAt: string;
+};
 
 async function signedIn(
   playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"],
@@ -19,6 +30,13 @@ function auditQuery(params: Record<string, string>): string {
   return `/api/audit-logs?${new URLSearchParams(params).toString()}`;
 }
 
+// Sign-in methods recorded for the account, oldest first.
+async function signInMethods(admin: APIRequestContext, email: string): Promise<unknown[]> {
+  const entries = (await (await admin.get(auditQuery({ action: "auth.login", target: email, order: "asc" }))).json()) as Entry[];
+  expect(entries.every((entry) => entry.actorEmail === email)).toBe(true);
+  return entries.map((entry) => entry.metadata?.method);
+}
+
 test("audit log records auth/admin actions", async ({ playwright, disposableUsers }) => {
   const admin = await signedIn(playwright, ADMIN);
   const probe = await admin.get("/api/audit-logs");
@@ -58,13 +76,22 @@ test("sending a verification email is audited", async ({ playwright, disposableU
   const admin = await signedIn(playwright, ADMIN);
   test.skip((await admin.get("/api/audit-logs")).status() === 404, "audit-log module not installed");
   const email = `verif-audit-${Date.now()}@example.com`;
-  const created = await admin.post("/api/auth/admin/create-user", {
-    data: { email, password: "Podokit3e-Str0ng!pw", name: "VA", role: "user" },
-  });
-  await disposableUsers.trackResponse(created);
-  await admin.post("/api/auth/send-verification-email", { data: { email, callbackURL: `${base}/admin` } });
-  const entries = (await (await admin.get(auditQuery({ action: "auth.verification_sent", target: email }))).json()) as Entry[];
+  await disposableUsers.create({ email, password: PASSWORD, name: "VA" });
+  const sent = async (): Promise<Entry[]> =>
+    (await (await admin.get(auditQuery({ action: "auth.verification_sent", target: email }))).json()) as Entry[];
+
+  // Better Auth sends a signed-in user's verification email only to their own address.
+  const refused = await admin.post("/api/auth/send-verification-email", { data: { email, callbackURL: `${base}/admin` } });
+  expect(refused.status()).toBe(400);
+  expect(await sent(), "a refused send is not audited").toEqual([]);
+
+  const user = await signedIn(playwright, { email, password: PASSWORD });
+  const own = await user.post("/api/auth/send-verification-email", { data: { email, callbackURL: `${base}/account` } });
+  expect(own.ok()).toBeTruthy();
+  const entries = await sent();
   expect(entries, "verification send should be audited").toHaveLength(1);
+  expect(entries[0]?.actorEmail).toBe(email);
+  await user.dispose();
   await admin.dispose();
 });
 
@@ -126,6 +153,68 @@ test("the audit log rejects bad paging parameters", async ({ playwright }) => {
   await admin.dispose();
 });
 
+test("a wrong password is not audited as a sign-in", async ({ playwright, disposableUsers }) => {
+  const admin = await signedIn(playwright, ADMIN);
+  test.skip((await admin.get("/api/audit-logs")).status() === 404, "audit-log module not installed");
+  const email = `audit-password-${Date.now()}@example.com`;
+  await disposableUsers.create({ email, password: PASSWORD });
+
+  const visitor = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const wrong = await visitor.post("/api/auth/sign-in/email", { data: { email, password: "Wrong-password-1" } });
+  expect(wrong.status()).toBe(401);
+  expect(await signInMethods(admin, email), "a failed sign-in leaves no auth.login").toEqual([]);
+
+  expect((await visitor.post("/api/auth/sign-in/email", { data: { email, password: PASSWORD } })).ok()).toBeTruthy();
+  expect(await signInMethods(admin, email)).toEqual(["password"]);
+  await visitor.dispose();
+  await admin.dispose();
+});
+
+test("an email code sign-in is audited once", async ({ playwright, disposableUsers }) => {
+  test.skip(!(await mailpitReachable()), "Mailpit not available");
+  const admin = await signedIn(playwright, ADMIN);
+  test.skip((await admin.get("/api/audit-logs")).status() === 404, "audit-log module not installed");
+  const caps = await (await admin.get("/api/account/capabilities")).json();
+  test.skip(!caps?.emailOtp, "email OTP not enabled");
+  const email = `audit-otp-${Date.now()}@example.com`;
+  await disposableUsers.create({ email, password: PASSWORD });
+
+  const visitor = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const sent = await visitor.post("/api/auth/email-otp/send-verification-otp", { data: { email, type: "sign-in" } });
+  expect(sent.ok()).toBeTruthy();
+  const otp = await waitForOtp(email);
+  expect((await visitor.post("/api/auth/sign-in/email-otp", { data: { email, otp } })).ok()).toBeTruthy();
+  expect(await signInMethods(admin, email)).toEqual(["email-otp"]);
+  await visitor.dispose();
+  await admin.dispose();
+});
+
+test("a two-factor sign-in is audited when the code completes it", async ({ playwright, disposableUsers }) => {
+  const admin = await signedIn(playwright, ADMIN);
+  test.skip((await admin.get("/api/audit-logs")).status() === 404, "audit-log module not installed");
+  const caps = await (await admin.get("/api/account/capabilities")).json();
+  test.skip(!caps?.twoFactor, "two-factor not enabled");
+  const email = `audit-2fa-${Date.now()}@example.com`;
+  await disposableUsers.create({ email, password: PASSWORD });
+
+  const owner = await signedIn(playwright, { email, password: PASSWORD });
+  const enable = await (await owner.post("/api/auth/two-factor/enable", { data: { password: PASSWORD } })).json();
+  expect((await owner.post("/api/auth/two-factor/verify-totp", { data: { code: totpCode(enable.totpURI) } })).ok()).toBeTruthy();
+  expect(await signInMethods(admin, email), "turning on two-factor is not a sign-in").toEqual(["password"]);
+
+  const challenged = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const pending = await (await challenged.post("/api/auth/sign-in/email", { data: { email, password: PASSWORD } })).json();
+  expect(pending.twoFactorRedirect).toBe(true);
+  expect(await signInMethods(admin, email), "the password step alone is not a sign-in").toEqual(["password"]);
+
+  const verified = await challenged.post("/api/auth/two-factor/verify-totp", { data: { code: totpCode(enable.totpURI) } });
+  expect(verified.ok()).toBeTruthy();
+  expect(await signInMethods(admin, email)).toEqual(["password", "two-factor-totp"]);
+  await owner.dispose();
+  await challenged.dispose();
+  await admin.dispose();
+});
+
 // Audit logging is a DB-backed on/off toggle (auth_config `server`, applied live).
 // Runs after the recording tests and restores the flag so nothing else is affected.
 test("audit logging honours the DB on/off toggle @smoke", { tag: "@exclusive" }, async ({ playwright, disposableUsers }) => {

package/dist/templates/modules/admin-dashboard/files/tests/api/auth.api.spec.ts

@@ -339,6 +339,17 @@ test("a user can create, list and delete an organization @smoke", async ({ playw
   const list = (await (await ctx.get("/api/auth/organization/list")).json()) as Array<{ id: string; slug: string }>;
   expect(list.some((o) => o.slug === slug)).toBeTruthy();
 
+  // A filter or a page that matches no member is an empty list, not a server error.
+  const userId = ((await (await ctx.get("/api/auth/get-session")).json()) as { user: { id: string } }).user.id;
+  const members = async (query: string): Promise<unknown> => {
+    const response = await ctx.get(`/api/auth/organization/list-members?organizationId=${orgId}&${query}`);
+    expect(response.status(), query).toBe(200);
+    return response.json();
+  };
+  expect(await members(`filterField=userId&filterValue=${userId}`)).toMatchObject({ members: [{ userId }], total: 1 });
+  expect(await members("filterField=userId&filterValue=not-a-member")).toEqual({ members: [], total: 0 });
+  expect(await members("offset=1")).toEqual({ members: [], total: 1 });
+
   const del = await ctx.post("/api/auth/organization/delete", { data: { organizationId: orgId } });
   expect(del.ok()).toBeTruthy();
   await ctx.dispose();

package/dist/templates/modules/admin-dashboard/files/tests/ui/theme-mode.ui.spec.ts

@@ -10,11 +10,11 @@ async function chooseTheme(page: Page, mode: "Light" | "Dark" | "System"): Promi
 // mode-watcher marks <html> with `.dark` or `.light`, so component libraries
 // that follow either class, and fall back to the OS setting otherwise, match the
 // theme the visitor chose rather than the system one. The managed ThemeToggle
-// renders on the page app-paths.ts names as the account menu page.
+// renders on the page app-paths.ts names as themeToggle.
 test("the chosen theme is named on <html> in both modes", async ({ page }) => {
-  test.skip(paths.accountMenu === null, "no page renders the theme toggle (tests/helpers/app-paths.ts)");
+  test.skip(paths.themeToggle === null, "no page renders the theme toggle (tests/helpers/app-paths.ts)");
   await page.emulateMedia({ colorScheme: "dark" });
-  await ready(page, paths.accountMenu ?? "/");
+  await ready(page, paths.themeToggle ?? "/");
   const html = page.locator("html");
 
   await chooseTheme(page, "Light");

package/dist/templates/modules/audit-log/files/apps/api/src/audit/README.md

@@ -8,10 +8,19 @@ actor / action / target model. Every entry flows through one pipeline
 
 Nothing is recorded automatically except the built-in **auth/admin actions**
 (login, user create/update/delete, ban, role change, session revoke, ...),
-which the better-auth hook (`audit-hook.ts`) maps to semantic action codes like
+which the Better Auth plugin in `audit-hook.ts` maps to semantic action codes like
 `user.create` and `auth.login`. Everything else is **opt-in** — you decide what
 matters.
 
+The plugin records an action only when the request succeeded, so a wrong
+password or a forbidden admin call leaves no entry. Every sign-in method records
+`auth.login` with the method in `metadata.method` (`password`, `email-otp`,
+`magic-link`, `passkey`, `two-factor-totp`, ...) and, for social sign-in, the
+provider in `metadata.provider`. A two-factor sign-in is recorded when the second
+factor completes it, not at the password step. `auth.ts` pushes the plugin after
+every other plugin: Better Auth runs after hooks in plugin order, and two-factor
+changes the outcome of a password sign-in in its own after hook.
+
 ## Audit your own Elysia routes
 
 ```ts
@@ -86,7 +95,10 @@ survives renames/deletes), `targetType/targetId/targetLabel`, `ip`, `metadata`
 
 ## Customize
 
-- **Auth actions:** edit the `ACTIONS` map in `audit-hook.ts`.
+- **Auth actions:** `ACTIONS` in `audit-hook.ts` maps Better Auth endpoints to
+  action codes, and `SIGN_IN_METHODS` lists the endpoints that sign a user in.
+  The `audit-hook.spec.ts` test fails when the app's Better Auth gains a sign-in
+  endpoint that neither list classifies.
 - **Your routes:** call `AuditService.recordRequest()` after successful operations;
   pass `{ defer: true }` only for high-volume, non-security events.
 - **Schema:** add columns with a migration, and keep the