@cosmicdrift/kumiko-samples 0.362.0 → 0.364.0

package/packages/bundled-features/src/template-resolver/handlers/template-write.ts

@@ -0,0 +1,233 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  type HandlerContext,
+  type SessionUser,
+  SYSTEM_TENANT_ID,
+  type TemplateVariables,
+  type TenantId,
+  type WriteResult,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  AccessDeniedError,
+  ValidationError,
+  type WriteFailure,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import { requireForTenant } from "../../shared/index.js";
+import type { ContentFormat, TemplateKind } from "../constants.js";
+import type { TemplateWriteScope } from "../layout-regions.js";
+import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
+import { activationChanges, serializeTemplateDraft } from "../template-draft.js";
+import type { TemplateValidation } from "../template-validation.js";
+import { executor } from "./shared.js";
+import {
+  evaluateTemplateWrite,
+  type TemplateWriteInput,
+  type TemplateWriteResult,
+} from "./template-gates.js";
+
+export type TemplateRowPayload = {
+  readonly slug: string;
+  readonly kind: TemplateKind;
+  readonly locale: string;
+  readonly content: string | null;
+  readonly contentFormat: ContentFormat;
+  readonly variableSchema: Readonly<Record<string, unknown>>;
+  readonly meta?: unknown;
+  readonly title?: string | null | undefined;
+  readonly folder?: string | null | undefined;
+  readonly parentTemplateId?: string | null | undefined;
+};
+
+export type WrittenTemplateRow = {
+  readonly id: string;
+  readonly slug: string;
+  readonly isNew: boolean;
+  readonly validation: TemplateValidation | null;
+};
+
+export type TemplateRowWrite = {
+  readonly ctx: HandlerContext;
+  readonly user: SessionUser;
+  readonly tenantId: TenantId;
+  readonly scope: TemplateWriteScope;
+  readonly status: "draft" | "active";
+  readonly variables: TemplateVariables;
+  readonly payload: TemplateRowPayload;
+};
+
+// The tenant-scope-under-system-tenant ban lives here so no write path can
+// create the inconsistent state the resolver does not model.
+export function refuseTenantScopeUnderSystemTenant(
+  scope: TemplateWriteScope,
+  tenantId: string,
+): WriteResult<never> | null {
+  if (scope !== "tenant" || tenantId !== SYSTEM_TENANT_ID) return null;
+  return writeFailure(
+    new AccessDeniedError({
+      i18nKey: "templateResolver.errors.useUpsertSystemForSystemTenant",
+      details: { reason: "system_tenant_override_not_allowed_use_upsert_system" },
+    }),
+  );
+}
+
+export type GatedTemplateWrite =
+  | { readonly ok: true; readonly evaluated: Extract<TemplateWriteResult, { ok: true }> }
+  | { readonly ok: false; readonly failure: WriteFailure };
+
+// Evaluation plus the publish rule: a row that goes active must not carry
+// publish issues, a draft may.
+export function gateTemplateWrite(
+  input: TemplateWriteInput,
+  status: "draft" | "active",
+): GatedTemplateWrite {
+  const evaluated = evaluateTemplateWrite(input);
+  if (!evaluated.ok) {
+    return {
+      ok: false,
+      failure: writeFailure(new ValidationError({ fields: [...evaluated.issues] })),
+    };
+  }
+  if (status === "active" && evaluated.publishIssues.length > 0) {
+    return {
+      ok: false,
+      failure: writeFailure(new ValidationError({ fields: [...evaluated.publishIssues] })),
+    };
+  }
+  return { ok: true, evaluated };
+}
+
+type TemplateRowFields = {
+  readonly content: string | null;
+  readonly contentFormat: ContentFormat;
+  readonly variableSchema: string;
+  readonly meta: string | null;
+  readonly title: string | null;
+  readonly folder: string | null;
+  readonly parentTemplateId: string | null;
+};
+
+// A draft over an active row is stored beside it; every other write replaces the main fields.
+function updateChanges(
+  existing: TemplateResourceRow,
+  status: "draft" | "active",
+  fields: TemplateRowFields,
+): Record<string, unknown> {
+  if (status === "active") return { ...fields, ...activationChanges(existing) };
+  if (existing.status !== "active") return { ...fields, status, draft: null };
+  const draft = serializeTemplateDraft({
+    content: fields.content,
+    contentFormat: fields.contentFormat,
+    variableSchema: fields.variableSchema,
+    meta: fields.meta,
+    title: fields.title,
+    folder: fields.folder,
+    parentTemplateId: fields.parentTemplateId,
+  });
+  return existing.activeVersion === null
+    ? {
+        draft,
+        activeVersion: existing.version,
+        activeSince: existing.modifiedAt ?? existing.insertedAt,
+      }
+    : { draft };
+}
+
+// Shared by every template write: validate through the one pipeline, then
+// create or update the (tenant, slug, kind, locale) row via the event-store
+// executor. linkedResources is never part of an update; resources are attached
+// separately.
+export async function writeTemplateRow(
+  args: TemplateRowWrite,
+): Promise<WriteResult<WrittenTemplateRow>> {
+  const { ctx, user, tenantId, scope, status, payload } = args;
+  const refused = refuseTenantScopeUnderSystemTenant(scope, tenantId);
+  if (refused !== null) return refused;
+  const { db, streamTenantId } = requireForTenant(ctx, tenantId);
+
+  const gated = gateTemplateWrite(
+    {
+      kind: payload.kind,
+      scope,
+      contentFormat: payload.contentFormat,
+      content: payload.content,
+      rawMeta: payload.meta,
+      variables: args.variables,
+    },
+    status,
+  );
+  if (!gated.ok) return gated.failure;
+  const { evaluated } = gated;
+
+  const existing = await fetchOne<TemplateResourceRow>(db, templateResourcesTable, {
+    tenantId,
+    slug: payload.slug,
+    kind: payload.kind,
+    locale: payload.locale,
+  });
+
+  const fields = {
+    slug: payload.slug,
+    kind: payload.kind,
+    locale: payload.locale,
+    content: evaluated.content,
+    contentFormat: payload.contentFormat,
+    variableSchema: JSON.stringify(payload.variableSchema),
+    meta: evaluated.metaJson,
+    title: payload.title ?? null,
+    folder: payload.folder ?? null,
+    scope,
+    parentTemplateId: payload.parentTemplateId ?? null,
+    status,
+  };
+
+  if (existing) {
+    const result = await executor.update(
+      {
+        id: existing.id,
+        version: existing.version,
+        changes: updateChanges(existing, status, fields),
+      },
+      user,
+      db,
+      { streamTenantId },
+    );
+    if (!result.isSuccess) return result;
+    return {
+      isSuccess: true,
+      data: {
+        id: String(existing.id),
+        slug: payload.slug,
+        isNew: false,
+        validation: evaluated.validation,
+      },
+    };
+  }
+
+  const result = await executor.create(
+    {
+      ...fields,
+      linkedResources: "{}",
+      tenantId,
+      draft: null,
+      ...(status === "active" ? activationChanges(null) : {}),
+    },
+    user,
+    db,
+    { streamTenantId },
+  );
+  if (!result.isSuccess) return result;
+  // @cast-boundary db-row — executor.create returnt Record-row aus
+  // INSERT RETURNING; shape { id } ist garantiert weil PK in der
+  // Returning-Klausel ist.
+  const createdRow = result.data as { id: string | number };
+  return {
+    isSuccess: true,
+    data: {
+      id: String(createdRow.id),
+      slug: payload.slug,
+      isNew: true,
+      validation: evaluated.validation,
+    },
+  };
+}

package/packages/bundled-features/src/template-resolver/handlers/tenant-overrides.query.ts

@@ -0,0 +1,137 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineQueryHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { TenantQueries } from "../../tenant/index.js";
+import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
+import { servedVersionOf } from "../template-draft.js";
+import { buildOverrideDiff } from "./override-diff.js";
+import { kindSchema, localeSchema, templateSlugSchema } from "./shared.js";
+
+const TENANT_OVERRIDES_REASON =
+  "SystemAdmin template overview lists which tenants override one system template; it reads tenant-scope template rows of every tenant (and the system row for the optional per-tenant diff), which the tenant-scoped db cannot reach";
+
+const tenantIdsSchema = z.array(z.string());
+const directorySchema = z.object({
+  rows: z.array(z.object({ id: z.string(), label: z.string() })),
+});
+
+type OverrideStatus = "active" | "draft";
+
+function labelsOf(raw: unknown): ReadonlyMap<string, string> {
+  return new Map(directorySchema.parse(raw).rows.map((row) => [row.id, row.label]));
+}
+
+// One row per tenant: its active override wins over a draft, then the newest version.
+function isBetterRow(candidate: TemplateResourceRow, current: TemplateResourceRow): boolean {
+  if ((candidate.status === "active") !== (current.status === "active")) {
+    return candidate.status === "active";
+  }
+  return candidate.version > current.version;
+}
+
+function statusOf(row: TemplateResourceRow): OverrideStatus {
+  return row.status === "active" ? "active" : "draft";
+}
+
+function isCountedTenantRow(
+  row: TemplateResourceRow,
+  enabledTenantIds: ReadonlySet<string> | null,
+): boolean {
+  if (row.tenantId === SYSTEM_TENANT_ID || row.status === "archived") return false;
+  return enabledTenantIds === null || enabledTenantIds.has(row.tenantId);
+}
+
+function pickBestRowPerTenant(
+  found: readonly TemplateResourceRow[],
+  enabledTenantIds: ReadonlySet<string> | null,
+): Map<string, TemplateResourceRow> {
+  const bestByTenant = new Map<string, TemplateResourceRow>();
+  for (const row of found) {
+    if (!isCountedTenantRow(row, enabledTenantIds)) continue;
+    const current = bestByTenant.get(row.tenantId);
+    if (current === undefined || isBetterRow(row, current)) bestByTenant.set(row.tenantId, row);
+  }
+  return bestByTenant;
+}
+
+function toOverrideRow(
+  row: TemplateResourceRow,
+  tenantLabels: ReadonlyMap<string, string>,
+  userLabels: ReadonlyMap<string, string>,
+) {
+  const changedById = row.modifiedById ?? row.insertedById;
+  return {
+    tenantId: row.tenantId,
+    tenantName: tenantLabels.get(row.tenantId) ?? row.tenantId,
+    templateId: String(row.id),
+    locale: row.locale,
+    status: statusOf(row),
+    version: servedVersionOf(row),
+    changedAt: (row.modifiedAt ?? row.insertedAt).toString(),
+    changedBy: changedById === null ? null : (userLabels.get(changedById) ?? null),
+  };
+}
+
+export const tenantOverridesQuery = defineQueryHandler({
+  name: "tenant-overrides",
+  schema: z.object({
+    slug: templateSlugSchema,
+    kind: kindSchema,
+    locale: localeSchema.optional(),
+    /** Adds the block diff of this tenant's override against the system template. */
+    diffTenantId: z.string().min(1).optional(),
+  }),
+  access: { roles: ["SystemAdmin"] },
+  description:
+    "Lists the enabled tenants that override one template with an active or a draft version (tenant name, status, version, last change and who made it), next to the counts and the number of enabled tenants; use it before changing a system template to see who keeps their own copy. With diffTenantId it also returns the block diff of that tenant's override against the system template.",
+  escapeHatch: { grants: ["unsafeRaw"], reason: TENANT_OVERRIDES_REASON },
+  handler: async (query, ctx) => {
+    const { slug, kind, locale, diffTenantId } = query.payload;
+    const raw = ctx.db.unsafeRaw();
+    const found = await selectMany<TemplateResourceRow>(raw, templateResourcesTable, {
+      slug,
+      kind,
+      scope: "tenant",
+      ...(locale === undefined ? {} : { locale }),
+    });
+
+    const hasTenantFeature =
+      ctx.registry.getQueryHandler(TenantQueries.activeTenantIds) !== undefined;
+    const enabledTenantIds = hasTenantFeature
+      ? new Set(tenantIdsSchema.parse(await ctx.query(TenantQueries.activeTenantIds, {})))
+      : null;
+
+    const bestByTenant = pickBestRowPerTenant(found, enabledTenantIds);
+    const best = [...bestByTenant.values()];
+    const tenantLabels = hasTenantFeature
+      ? labelsOf(await ctx.query(TenantQueries.tenantDirectory, {}))
+      : new Map<string, string>();
+    const userLabels = hasTenantFeature
+      ? labelsOf(await ctx.query(TenantQueries.memberDirectory, {}))
+      : new Map<string, string>();
+
+    const rows = best
+      .map((row) => toOverrideRow(row, tenantLabels, userLabels))
+      .sort((a, b) => a.tenantName.localeCompare(b.tenantName));
+
+    let diff: ReturnType<typeof buildOverrideDiff> | null = null;
+    const diffRow = diffTenantId === undefined ? undefined : bestByTenant.get(diffTenantId);
+    if (diffRow !== undefined) {
+      const [systemRow] = await selectMany<TemplateResourceRow>(raw, templateResourcesTable, {
+        tenantId: SYSTEM_TENANT_ID,
+        slug,
+        kind,
+        locale: diffRow.locale,
+      });
+      if (systemRow !== undefined) diff = buildOverrideDiff(diffRow, systemRow);
+    }
+
+    return {
+      activeOverrides: best.filter((row) => row.status === "active").length,
+      draftOverrides: best.filter((row) => row.status !== "active").length,
+      totalTenants: enabledTenantIds === null ? null : enabledTenantIds.size,
+      rows,
+      diff,
+    };
+  },
+});

package/packages/bundled-features/src/template-resolver/handlers/toggle-status.write.ts

@@ -1,46 +1,120 @@
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
-import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
-import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  defineWriteHandler,
+  type HandlerContext,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  NotFoundError,
+  ValidationError,
+  type WriteFailure,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
+import { requireForTenant } from "../../shared/index.js";
 import type { TemplateResourceRow } from "../table.js";
 import { templateResourcesTable } from "../table.js";
+import { activationChanges, parseTemplateDraft, toWorkingRow } from "../template-draft.js";
 import { executor } from "./shared.js";
+import { publishGateIssues } from "./template-gates.js";
 
 type TemplateStatus = "active" | "archived";
+export type StatusTarget = "own" | "system";
 
-function createStatusUpdateHandler(name: string, status: TemplateStatus, description: string) {
+function isRowOfTarget(row: TemplateResourceRow, target: StatusTarget, callerTenantId: string) {
+  return target === "system"
+    ? row.tenantId === SYSTEM_TENANT_ID && row.scope === "system"
+    : row.tenantId === callerTenantId && row.scope === "tenant";
+}
+
+export function writeAccessFor(target: StatusTarget) {
+  return { roles: target === "system" ? ["SystemAdmin"] : ["TenantAdmin", "SystemAdmin"] };
+}
+
+// The tenant db also reads system rows; the row's own tenant must match the
+// target or the executor would append to a foreign event stream.
+export async function loadTargetRow(
+  ctx: HandlerContext,
+  target: StatusTarget,
+  user: { readonly tenantId: string },
+  id: string,
+) {
+  const scoped = target === "system" ? requireForTenant(ctx, SYSTEM_TENANT_ID) : null;
+  const db = scoped?.db ?? ctx.db;
+  const row = await fetchOne<TemplateResourceRow>(db, templateResourcesTable, { id });
+  return { db, scoped, row: row && isRowOfTarget(row, target, user.tenantId) ? row : null };
+}
+
+type StatusPlan =
+  | { readonly ok: true; readonly changes: Record<string, unknown> }
+  | { readonly ok: false; readonly failure: WriteFailure };
+
+// Publishing promotes an open draft (gated as the version that goes live); a row
+// without one is activated as stored. Archiving leaves the draft standing.
+function planStatusChange(
+  ctx: HandlerContext,
+  row: TemplateResourceRow,
+  status: TemplateStatus,
+): StatusPlan {
+  if (status === "archived") return { ok: true, changes: { status } };
+  const issues = publishGateIssues(ctx.registry, toWorkingRow(row, row.tenantId));
+  if (issues.length > 0) {
+    return { ok: false, failure: writeFailure(new ValidationError({ fields: [...issues] })) };
+  }
+  return { ok: true, changes: { ...parseTemplateDraft(row.draft), ...activationChanges(row) } };
+}
+
+function createStatusUpdateHandler(
+  name: string,
+  target: StatusTarget,
+  status: TemplateStatus,
+  description: string,
+) {
   return defineWriteHandler({
     name,
     schema: z.object({ id: z.string().min(1) }),
-    access: { roles: ["TenantAdmin", "SystemAdmin"] },
+    access: writeAccessFor(target),
+    // A system template change reaches every tenant without an override.
+    ...(target === "system" ? { agent: { risk: "high" as const } } : {}),
     description,
     handler: async (event, ctx) => {
-      // ctx.db is tenant-scoped: a foreign tenant's id reads as absent → NotFound.
-      // Cross-tenant toggling needs SystemAdmin with tenantIdOverride.
-      const existing = await fetchOne<TemplateResourceRow>(ctx.db, templateResourcesTable, {
-        id: event.payload.id,
-      });
-      if (!existing) {
-        return writeFailure(new NotFoundError("template-resource", event.payload.id));
-      }
+      const { db, scoped, row } = await loadTargetRow(ctx, target, event.user, event.payload.id);
+      if (!row) return writeFailure(new NotFoundError("template-resource", event.payload.id));
+      const plan = planStatusChange(ctx, row, status);
+      if (!plan.ok) return plan.failure;
       const result = await executor.update(
-        { id: existing.id, version: existing.version, changes: { status } },
+        { id: row.id, version: row.version, changes: plan.changes },
         event.user,
-        ctx.db,
+        db,
+        scoped ? { streamTenantId: scoped.streamTenantId } : undefined,
       );
       if (!result.isSuccess) return result;
-      return { isSuccess: true as const, data: { id: String(existing.id), status } };
+      return { isSuccess: true as const, data: { id: String(row.id), status } };
     },
   });
 }
 
 export const archiveWrite = createStatusUpdateHandler(
   "archive",
+  "own",
   "archived",
-  "Sets one template resource of the caller's tenant to archived so the resolver stops serving it while the row and its content survive; use it to retire a template reversibly instead of deleting it.",
+  "Sets one template resource of the caller's tenant to archived so the resolver stops serving it while the row and its content survive; use it to retire a template reversibly instead of deleting it. An open draft stays.",
 );
 export const publishWrite = createStatusUpdateHandler(
   "publish",
+  "own",
+  "active",
+  "Sets one template resource of the caller's tenant to active so the resolver starts serving it; use it to release a draft written by upsert-tenant (a draft saved beside an active version replaces it), or to bring an archived template back; a version with unknown placeholders or unused required variables is refused and the served version stays.",
+);
+export const archiveSystemWrite = createStatusUpdateHandler(
+  "archive-system",
+  "system",
+  "archived",
+  "Sets one system-default template to archived so the resolver stops serving it to every tenant that has no override; SystemAdmin only, reversible with publish-system.",
+);
+export const publishSystemWrite = createStatusUpdateHandler(
+  "publish-system",
+  "system",
   "active",
-  "Sets one template resource of the caller's tenant to active so the resolver starts serving it; use it to release a draft written by upsert-tenant, or to bring an archived template back.",
+  "Sets one system-default template to active so the resolver serves it again to every tenant that has no override; an open draft beside the active version replaces it; SystemAdmin only, a version with unknown placeholders or unused required variables is refused.",
 );

package/packages/bundled-features/src/template-resolver/handlers/upsert-system.write.ts

@@ -1,13 +1,7 @@
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
-import {
-  defineWriteHandler,
-  SYSTEM_TENANT_ID,
-  type TenantId,
-} from "@cosmicdrift/kumiko-framework/engine";
-import { requireForTenant } from "../../shared/index.js";
-import type { TemplateResourceRow } from "../table.js";
-import { templateResourcesTable } from "../table.js";
-import { executor, upsertPayloadSchema } from "./shared.js";
+import { defineWriteHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { resolveTemplateVariables } from "../template-validation.js";
+import { upsertPayloadSchema } from "./shared.js";
+import { writeTemplateRow } from "./template-write.js";
 
 // System-Template anlegen/updaten. Liegt unter SYSTEM_TENANT_ID,
 // scope='system'. Nur SystemAdmin (globale Rolle). TenantAdmin kann
@@ -18,65 +12,19 @@ export const upsertSystemWrite = defineWriteHandler({
   schema: upsertPayloadSchema,
   access: { roles: ["SystemAdmin"] },
   description:
-    "Creates or overwrites a system-default template under the system tenant with its full variable schema and linked resources, active straight away with no draft stage; SystemAdmin only, since tenants shadow these defaults through upsert-tenant instead.",
-  handler: async (event, ctx) => {
-    // @cast-boundary engine-payload — SYSTEM_TENANT_ID is a UUID literal,
-    // asserted to the branded TenantId (parseTenantId equivalent).
-    const tenantId = SYSTEM_TENANT_ID as TenantId;
-    const { db, streamTenantId } = requireForTenant(ctx, tenantId);
-
-    const existing = await fetchOne<TemplateResourceRow>(db, templateResourcesTable, {
-      tenantId,
-      slug: event.payload.slug,
-      kind: event.payload.kind,
-      locale: event.payload.locale,
-    });
-
-    const fields = {
-      slug: event.payload.slug,
-      kind: event.payload.kind,
-      locale: event.payload.locale,
-      content: event.payload.content,
-      contentFormat: event.payload.contentFormat,
-      variableSchema: JSON.stringify(event.payload.variableSchema),
-      linkedResources: JSON.stringify(event.payload.linkedResources),
-      title: event.payload.title ?? null,
-      folder: event.payload.folder ?? null,
-      scope: "system" as const,
-      parentTemplateId: event.payload.parentTemplateId ?? null,
-      // System-Defaults sind sofort active (kein draft-Stage für seeds).
-      status: "active" as const,
-    };
-
-    if (existing) {
-      const result = await executor.update(
-        { id: existing.id, version: existing.version, changes: fields },
-        event.user,
-        db,
-        { streamTenantId },
-      );
-      if (!result.isSuccess) return result;
-      return {
-        isSuccess: true as const,
-        data: { id: String(existing.id), slug: event.payload.slug, isNew: false },
-      };
-    }
-
-    const result = await executor.create({ ...fields, tenantId }, event.user, db, {
-      streamTenantId,
-    });
-    if (!result.isSuccess) return result;
-    // @cast-boundary db-row — executor.create returnt Record-row aus
-    // INSERT RETURNING; shape { id } ist garantiert weil PK in der
-    // Returning-Klausel ist.
-    const createdRow = result.data as { id: string | number };
-    return {
-      isSuccess: true as const,
-      data: {
-        id: String(createdRow.id),
-        slug: event.payload.slug,
-        isNew: true,
-      },
-    };
-  },
+    "Creates or overwrites a system-default template under the system tenant with its full variable schema (resource files go through the resource upload), active straight away with no draft stage; SystemAdmin only, since tenants shadow these defaults through upsert-tenant instead.",
+  handler: (event, ctx) =>
+    writeTemplateRow({
+      ctx,
+      user: event.user,
+      tenantId: SYSTEM_TENANT_ID,
+      scope: "system",
+      status: "active",
+      variables: resolveTemplateVariables(
+        ctx.registry,
+        event.payload.slug,
+        event.payload.variableSchema,
+      ),
+      payload: event.payload,
+    }),
 });