@cosmicdrift/kumiko-samples 0.390.0 → 0.391.0

package/packages/bundled-features/src/readiness/handlers/run-probes.write.ts

@@ -0,0 +1,98 @@
+// Starts a system-check run. The job on the worker lane (run-probes-job.ts) executes it after commit.
+//
+// Idempotency: an app-side pre-check returns the active run; the partial UNIQUE index
+// (ACTIVE_PROBE_RUN_CONSTRAINT) catches a click that slips in between check and create (23505).
+
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import type { WriteFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+import * as z from "zod";
+import { staleRunAfterMs } from "../collect-probes.ts";
+import {
+  ACTIVE_PROBE_RUN_CONSTRAINT,
+  PROBE_RUN_STATUS,
+  probeRunEntity,
+  probeRunsTable,
+} from "../schema/probe-run.ts";
+
+const crud = createEventStoreExecutor(probeRunsTable, probeRunEntity, {
+  entityName: "probe-run",
+});
+
+const ACTIVE_STATUSES = [PROBE_RUN_STATUS.Pending, PROBE_RUN_STATUS.Running];
+
+type ActiveRunRow = {
+  readonly id: string;
+  readonly version: number;
+  readonly requestedAt: { readonly epochMilliseconds: number };
+};
+
+function isActiveRunConflict(failure: WriteFailure): boolean {
+  return (
+    failure.error.code === "unique_violation" &&
+    propertyOf(failure.error.details, "constraintName") === ACTIVE_PROBE_RUN_CONSTRAINT
+  );
+}
+
+export const runProbesWrite = defineWriteHandler({
+  name: "run-probes",
+  schema: z.object({ includePaid: z.boolean().default(false) }),
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  description:
+    "Starts the system check: real calls against mail, storage, search, inbound mailboxes and PDF that show what works in this environment. Returns the run id (isExisting true while a run is still active); the worker fills the run, read the outcome via readiness:query:probe-run:latest-results. Paid probes only run with includePaid true.",
+  handler: async (event, ctx) => {
+    if (!ctx.services.jobRunner) {
+      throw new InternalError({
+        message: "readiness:run-probes needs a job runner; mount the jobs infrastructure",
+      });
+    }
+
+    const findActive = () =>
+      ctx.db.fetchOne<ActiveRunRow>(probeRunsTable, { status: ACTIVE_STATUSES });
+
+    const nowMs = ctx.tz.now().epochMilliseconds;
+    const active = await findActive();
+    if (active) {
+      if (nowMs - active.requestedAt.epochMilliseconds <= staleRunAfterMs(ctx.registry)) {
+        return { isSuccess: true as const, data: { runId: active.id, isExisting: true } };
+      }
+      const abandoned = await crud.update(
+        {
+          id: active.id,
+          version: active.version,
+          changes: { status: PROBE_RUN_STATUS.Abandoned, finishedAt: ctx.tz.now() },
+        },
+        event.user,
+        ctx.db,
+      );
+      if (!abandoned.isSuccess) return abandoned;
+    }
+
+    const created = await crud.create(
+      {
+        status: PROBE_RUN_STATUS.Pending,
+        includePaid: event.payload.includePaid,
+        includeSystemProbes: event.user.roles.includes("SystemAdmin"),
+        triggeredByUserId: event.user.id,
+        requestedAt: ctx.tz.now(),
+        results: { rows: [] },
+        tenantId: event.user.tenantId,
+      },
+      event.user,
+      ctx.db,
+    );
+    if (created.isSuccess) {
+      return {
+        isSuccess: true as const,
+        data: { runId: String(created.data.id), isExisting: false },
+      };
+    }
+    if (!isActiveRunConflict(created)) return created;
+
+    const winner = await findActive();
+    if (!winner) return created;
+    return { isSuccess: true as const, data: { runId: winner.id, isExisting: true } };
+  },
+});

package/packages/bundled-features/src/readiness/handlers/run-results.query.ts

@@ -0,0 +1,18 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { type RunRow, viewRun } from "../run-view.ts";
+import { probeRunsTable } from "../schema/probe-run.ts";
+
+export const runResultsQuery = defineQueryHandler({
+  name: "probe-run:results",
+  schema: z.object({ runId: z.uuid() }),
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  description:
+    "Returns the per-probe results of one system-check run of the caller's tenant, filtered to what the caller may see: system probes only for SystemAdmin, personal mailboxes only for their owner.",
+  handler: async (query, ctx) => {
+    const run = await ctx.db.fetchOne<RunRow>(probeRunsTable, { id: query.payload.runId });
+    if (!run) throw new NotFoundError("probe-run", query.payload.runId);
+    return { rows: viewRun(run, query.user).results, nextCursor: null };
+  },
+});

package/packages/bundled-features/src/readiness/handlers/run-tone.ts

@@ -0,0 +1,6 @@
+import type { RunOutcome } from "../visible-results.ts";
+
+export function toneOf(outcome: RunOutcome): "default" | "positive" | "negative" {
+  if (outcome === "running") return "default";
+  return outcome === "ok" ? "positive" : "negative";
+}

package/packages/bundled-features/src/readiness/i18n.ts

@@ -0,0 +1,55 @@
+type LocalizedString = { readonly en: string };
+
+export const READINESS_I18N: Readonly<Record<string, LocalizedString>> = {
+  "readiness.area.infrastructure": { en: "Infrastructure" },
+  "readiness.area.run": { en: "System check" },
+  "readiness.probe.run": { en: "Run of the system check" },
+  "readiness.probe.database.label": { en: "Database" },
+  "readiness.probe.database.ok": { en: "Database reachable" },
+  "readiness.probe.cache.label": { en: "Cache" },
+  "readiness.probe.cache.ok": { en: "Cache reachable" },
+  "readiness.probe.search.label": { en: "Search" },
+  "readiness.probe.search.ok": { en: "Search reachable" },
+  "readiness.probe.paid-not-requested": { en: "Not run, paid checks were not requested" },
+  "readiness.probe.no-targets": { en: "Nothing to check" },
+  "readiness.probe.timeout": { en: "No answer after {seconds} seconds" },
+  "readiness.probe.failed": { en: "The check failed" },
+  "readiness.probe.run-crashed": { en: "The check run stopped unexpectedly" },
+  "readiness.probe.not-configured": { en: "Not set up" },
+  "readiness.summary.ok-of-total": { en: "{ok} of {total} checks passed" },
+  "readiness.summary.running": { en: "The check is running" },
+  "readiness.summary.no-run": { en: "No check has run yet" },
+  "readiness:nav.systemCheck": { en: "System check" },
+  "screen:system-check.title": { en: "System check" },
+  "screen:system-check-run.title": { en: "System check run" },
+  "readiness.screen.action.run": { en: "Start check" },
+  "readiness.screen.action.run-paid": { en: "Test AI extraction · about 1 cent" },
+  "readiness.screen.latest.title": { en: "Latest run" },
+  "readiness.screen.latest.description": {
+    en: "Real calls against mail, storage, search and the other connected services. A failed row links to the screen that fixes it.",
+  },
+  "readiness.screen.latest.empty": { en: "No results yet. Start a check." },
+  "readiness.screen.history.title": { en: "History" },
+  "readiness.screen.history.description": {
+    en: "Earlier runs, newest first. Open one to see its results.",
+  },
+  "readiness.screen.history.empty": { en: "No check has run yet." },
+  "readiness.screen.run.results-title": { en: "Results" },
+  "readiness.screen.metric.ok": { en: "Passed" },
+  "readiness.screen.metric.failed": { en: "Failed" },
+  "readiness.screen.metric.skipped": { en: "Not run" },
+  "readiness.screen.column.area": { en: "Area" },
+  "readiness.screen.column.check": { en: "Check" },
+  "readiness.screen.column.status": { en: "Status" },
+  "readiness.screen.column.duration": { en: "Duration (ms)" },
+  "readiness.screen.column.result": { en: "Result" },
+  "readiness.screen.column.started": { en: "Started" },
+  "readiness.screen.column.started-by": { en: "By" },
+  "readiness.screen.column.outcome": { en: "Outcome" },
+  "readiness.result-status.ok": { en: "OK" },
+  "readiness.result-status.failed": { en: "Failed" },
+  "readiness.result-status.skipped": { en: "Not run" },
+  "readiness.outcome.ok": { en: "No failures" },
+  "readiness.outcome.failed": { en: "Failures" },
+  "readiness.outcome.running": { en: "Running" },
+};

package/packages/bundled-features/src/readiness/index.ts

@@ -1,3 +1,3 @@
-export { READINESS_FEATURE, ReadinessQueries } from "./constants.ts";
+export { READINESS_FEATURE, ReadinessQueries, ReadinessWrites } from "./constants.ts";
 export { createReadinessFeature } from "./feature.ts";
 export type { ReadinessMissingSecret } from "./handlers/status.query.ts";

package/packages/bundled-features/src/readiness/probe-boot-check.ts

@@ -0,0 +1,53 @@
+import {
+  buildConfigFeatureSchema,
+  createRegistry,
+  type FeatureDefinition,
+  SETTINGS_HUB_FEATURE,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// Settings screens come from config keys at schema build, not from r.screen, yet a probe may
+// link a failed row to one (mail sending lives on config:screen:mail-foundation-tenant).
+function mountedScreenQns(features: readonly FeatureDefinition[]): ReadonlySet<string> {
+  const generatedSettings = buildConfigFeatureSchema(createRegistry(features)).screens.map(
+    (screen) => `${SETTINGS_HUB_FEATURE}:screen:${screen.id}`,
+  );
+  return new Set([
+    ...features.flatMap((feature) =>
+      Object.keys(feature.screens).map((screenId) => `${feature.name}:screen:${screenId}`),
+    ),
+    ...generatedSettings,
+  ]);
+}
+
+// A probe whose area or label has no translation would render a raw key in the result table,
+// and one whose fixScreen names no mounted screen would link a failed row nowhere.
+export function validateProbeTranslations(features: readonly FeatureDefinition[]): void {
+  const screenQns = mountedScreenQns(features);
+  const defined = new Set<string>();
+  for (const feature of features) {
+    for (const key of Object.keys(feature.translations)) {
+      defined.add(key);
+      const colon = key.indexOf(":");
+      if (colon > 0) defined.add(key.slice(colon + 1));
+    }
+  }
+  for (const feature of features) {
+    for (const probe of Object.values(feature.probes ?? {})) {
+      for (const [field, key] of [
+        ["area", probe.area],
+        ["label", probe.label],
+      ] as const) {
+        if (!defined.has(key)) {
+          throw new Error(
+            `Probe "${probe.qualifiedName}": ${field} translation key "${key}" is not defined by any mounted feature. Add it via r.translations(...).`,
+          );
+        }
+      }
+      if (probe.fixScreen !== undefined && !screenQns.has(probe.fixScreen)) {
+        throw new Error(
+          `Probe "${probe.qualifiedName}": fixScreen "${probe.fixScreen}" is not a screen of any mounted feature. Use a "<feature>:screen:<id>" QN.`,
+        );
+      }
+    }
+  }
+}

package/packages/bundled-features/src/readiness/probe-context.ts

@@ -0,0 +1,57 @@
+import {
+  createSystemUser,
+  type JobContext,
+  type ProbeContext,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { decryptStoredUserEmail } from "../shared/index.ts";
+import { UserQueries } from "../user/index.ts";
+
+const triggeringUserRowSchema = z.object({
+  email: z.string().optional(),
+  isDeleted: z.boolean().nullish(),
+});
+
+async function resolveTriggeredByEmail(
+  ctx: JobContext,
+  tenantId: TenantId,
+  userId: string,
+): Promise<string | undefined> {
+  if (!ctx.registry.features.has("user")) return undefined;
+  let found: unknown;
+  try {
+    found = await ctx.dispatch.queryAs(createSystemUser(tenantId), UserQueries.findForAuth, {
+      id: userId,
+    });
+  } catch (error) {
+    // Probes that need the address skip themselves; the lookup must not take the whole run down.
+    ctx.obs.log.warn("readiness could not look up the run starter", {
+      error: error instanceof Error ? error.name : "unknown",
+    });
+    return undefined;
+  }
+  const row = triggeringUserRowSchema.safeParse(found);
+  if (!row.success || row.data.email === undefined || row.data.isDeleted === true) {
+    return undefined;
+  }
+  return (await decryptStoredUserEmail(row.data.email, "readiness:run-probes")) ?? undefined;
+}
+
+export async function buildProbeContext(
+  ctx: JobContext,
+  run: { readonly id: string; readonly triggeredByUserId: string },
+  tenantId: TenantId,
+): Promise<ProbeContext> {
+  return {
+    db: ctx.db,
+    registry: ctx.registry,
+    obs: ctx.obs,
+    tz: ctx.tz,
+    services: ctx.services,
+    probeRunId: run.id,
+    tenantId,
+    triggeredByUserId: run.triggeredByUserId,
+    triggeredByEmail: await resolveTriggeredByEmail(ctx, tenantId, run.triggeredByUserId),
+  };
+}

package/packages/bundled-features/src/readiness/run-probes-job.ts

@@ -0,0 +1,104 @@
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { createSystemUser, type JobContext } from "@cosmicdrift/kumiko-framework/engine";
+import { collectProbes } from "./collect-probes.ts";
+import { ProbeTextKeys } from "./constants.ts";
+import { executeProbes } from "./execute-probes.ts";
+import { buildProbeContext } from "./probe-context.ts";
+import {
+  PROBE_RUN_STATUS,
+  type ProbeResultRow,
+  probeRunEntity,
+  probeRunsTable,
+} from "./schema/probe-run.ts";
+
+const crud = createEventStoreExecutor(probeRunsTable, probeRunEntity, {
+  entityName: "probe-run",
+});
+
+type PendingRunRow = {
+  readonly id: string;
+  readonly version: number;
+  readonly includePaid: boolean;
+  readonly includeSystemProbes: boolean;
+  readonly triggeredByUserId: string;
+};
+
+function countStatus(rows: readonly ProbeResultRow[], status: ProbeResultRow["status"]): number {
+  return rows.filter((row) => row.status === status).length;
+}
+
+// Runs the pending run of the job's tenant; the write handler guarantees at most one active run per tenant.
+export async function runProbesJob(_payload: Record<string, unknown>, ctx: JobContext) {
+  const tenantId = ctx.db.tenantId;
+  const run = await ctx.db.fetchOne<PendingRunRow>(probeRunsTable, {
+    status: PROBE_RUN_STATUS.Pending,
+  });
+  // skip: no pending run left, e.g. a second trigger after the first job already claimed it.
+  if (!run) return;
+
+  const executor = createSystemUser(tenantId);
+  const startedAt = ctx.tz.now();
+  const claimed = await crud.update(
+    {
+      id: run.id,
+      version: run.version,
+      changes: { status: PROBE_RUN_STATUS.Running, startedAt },
+    },
+    executor,
+    ctx.db,
+  );
+  // skip: a second job for the same run claimed it first
+  if (!claimed.isSuccess) return;
+
+  let rows: readonly ProbeResultRow[] = [];
+  try {
+    const probes = collectProbes(ctx.registry, {
+      includeSystemProbes: run.includeSystemProbes,
+      enabledFeatures: ctx.services.effectiveFeatures?.(tenantId),
+    });
+    const probeContext = await buildProbeContext(ctx, run, tenantId);
+    rows = await executeProbes(probeContext, probes, run.includePaid);
+  } catch (error) {
+    ctx.obs.log.warn("readiness run crashed", {
+      runId: run.id,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    rows = [
+      ...rows,
+      {
+        probe: "readiness:probe:run",
+        scope: "tenant",
+        area: "readiness.area.run",
+        label: { key: "readiness.probe.run" },
+        status: "failed",
+        durationMs: null,
+        message: { key: ProbeTextKeys.runCrashed },
+      },
+    ];
+  } finally {
+    const finishedAt = ctx.tz.now();
+    const done = await crud.update(
+      {
+        id: run.id,
+        version: run.version + 1,
+        changes: {
+          status: PROBE_RUN_STATUS.Done,
+          finishedAt,
+          durationMs: finishedAt.epochMilliseconds - startedAt.epochMilliseconds,
+          okCount: countStatus(rows, "ok"),
+          failedCount: countStatus(rows, "failed"),
+          skippedCount: countStatus(rows, "skipped"),
+          results: { rows },
+        },
+      },
+      executor,
+      ctx.db,
+    );
+    if (!done.isSuccess) {
+      ctx.obs.log.warn("readiness run could not be finished", {
+        runId: run.id,
+        code: done.error.code,
+      });
+    }
+  }
+}

package/packages/bundled-features/src/readiness/run-view.ts

@@ -0,0 +1,48 @@
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { PROBE_RUN_STATUS, probeRunsTable } from "./schema/probe-run.ts";
+import {
+  countResults,
+  outcomeOf,
+  type ResultCounts,
+  type RunOutcome,
+  type VisibleProbeResult,
+  visibleResults,
+} from "./visible-results.ts";
+
+type InstantLike = { readonly toString: () => string };
+
+export type RunRow = {
+  readonly id: string;
+  readonly status: string;
+  readonly requestedAt: InstantLike;
+  readonly startedAt: InstantLike | null;
+  readonly finishedAt: InstantLike | null;
+  readonly triggeredByUserId: string;
+  readonly durationMs: number | null;
+  readonly results: unknown;
+};
+
+export type RunView = {
+  readonly results: readonly VisibleProbeResult[];
+  readonly counts: ResultCounts;
+  readonly outcome: RunOutcome;
+};
+
+export const HISTORY_LIMIT = 100;
+
+export async function fetchLatestRun(db: TenantDb): Promise<RunRow | undefined> {
+  const [latest] = await db.selectMany<RunRow>(
+    probeRunsTable,
+    { status: [PROBE_RUN_STATUS.Pending, PROBE_RUN_STATUS.Running, PROBE_RUN_STATUS.Done] },
+    { limit: 1, orderBy: { col: "requestedAt", direction: "desc" } },
+  );
+  return latest;
+}
+
+// Counts come from the results the caller may see, so a TenantAdmin never learns about system failures.
+export function viewRun(run: RunRow, user: SessionUser): RunView {
+  const results = visibleResults(run.results, user);
+  const counts = countResults(results);
+  return { results, counts, outcome: outcomeOf(run.status, counts) };
+}

package/packages/bundled-features/src/readiness/schema/probe-run.ts

@@ -0,0 +1,89 @@
+import { buildEntityTable, sql } from "@cosmicdrift/kumiko-framework/db";
+import type { ProbeScope, ProbeText } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createBooleanField,
+  createEntity,
+  createJsonbField,
+  createNumberField,
+  createSelectField,
+  createTextField,
+  createTimestampField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+export const PROBE_RUN_STATUS = {
+  Pending: "pending",
+  Running: "running",
+  Done: "done",
+  Abandoned: "abandoned",
+} as const;
+
+export type ProbeRunStatus = (typeof PROBE_RUN_STATUS)[keyof typeof PROBE_RUN_STATUS];
+
+export const ACTIVE_PROBE_RUN_CONSTRAINT = "read_readiness_probe_runs_one_active_per_tenant";
+
+const PROBE_RUN_STATUS_OPTIONS = [
+  PROBE_RUN_STATUS.Pending,
+  PROBE_RUN_STATUS.Running,
+  PROBE_RUN_STATUS.Done,
+  PROBE_RUN_STATUS.Abandoned,
+] as const;
+
+export type ProbeResultStatus = "ok" | "failed" | "skipped";
+
+// Texts are i18n keys plus short scalar params, never raw error messages or addresses.
+export type ProbeResultRow = {
+  readonly probe: string;
+  readonly scope: ProbeScope;
+  readonly area: string;
+  readonly label: ProbeText;
+  readonly targetId?: string;
+  readonly ownerUserId?: string;
+  readonly status: ProbeResultStatus;
+  readonly durationMs: number | null;
+  readonly message: ProbeText;
+  readonly fixScreen?: string;
+};
+
+// A jsonb field only accepts a plain object at the write boundary, so the rows sit under one key.
+export type ProbeRunResults = { readonly rows: readonly ProbeResultRow[] };
+
+export const probeRunEntity = createEntity({
+  table: "read_readiness_probe_runs",
+  idType: "uuid",
+  description:
+    "One system-check run of a tenant: who started it, whether paid and system probes were requested, its pending/running/done/abandoned status, the timing and the per-probe results with their translated texts and outcome counts.",
+
+  fields: {
+    status: createSelectField({
+      required: true,
+      default: PROBE_RUN_STATUS.Pending,
+      options: PROBE_RUN_STATUS_OPTIONS,
+    }),
+    includePaid: createBooleanField({}),
+    includeSystemProbes: createBooleanField({}),
+    triggeredByUserId: createTextField({
+      required: true,
+      personal: false,
+      reason: "pseudonymous_fk",
+    }),
+    requestedAt: createTimestampField({ required: true, sortable: true }),
+    startedAt: createTimestampField({}),
+    finishedAt: createTimestampField({}),
+    durationMs: createNumberField({ integer: true }),
+    okCount: createNumberField({ integer: true }),
+    failedCount: createNumberField({ integer: true }),
+    skippedCount: createNumberField({ integer: true }),
+    results: createJsonbField({ personal: false, reason: "is_business_data" }),
+  },
+
+  indexes: [
+    {
+      unique: true,
+      columns: ["tenantId"],
+      name: ACTIVE_PROBE_RUN_CONSTRAINT,
+      where: sql`status IN ('pending', 'running')`,
+    },
+  ],
+});
+
+export const probeRunsTable = buildEntityTable("probeRun", probeRunEntity);