@cosmicdrift/kumiko-samples 0.362.0 → 0.363.0

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

@@ -4,8 +4,11 @@ import {
   defineWriteHandler,
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { ValidationError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { requireForTenant } from "../../shared/index.js";
+import { COLLECTION_REFUSED_KINDS } from "../constants.js";
+import { documentViolationsToFieldIssues, sanitizeTemplateBody } from "../document-sanitizer.js";
 import {
   type CollectionEntryRow,
   collectionStore,
@@ -40,6 +43,20 @@ export function makeCollectionSetWrite(collection: ContentCollectionDefinition)
         ? `Creates or overwrites the caller's own "${collection.id}" entry at a slug and locale, live on save with no draft stage; it always writes the acting user's entry, never another user's.`
         : `Creates or overwrites the tenant-wide "${collection.id}" entry at a slug and locale, live on save with no draft stage; the change is visible to everyone who may reach this shared collection.`,
     handler: async (event, ctx) => {
+      if (COLLECTION_REFUSED_KINDS.includes(collection.kind)) {
+        return writeFailure(
+          new ValidationError({
+            fields: [
+              {
+                path: "kind",
+                code: "kind_not_allowed",
+                i18nKey: "templateResolver.errors.collection.kindNotAllowed",
+                params: { detail: collection.kind },
+              },
+            ],
+          }),
+        );
+      }
       const override = event.payload.tenantIdOverride;
       // @cast-boundary engine-payload — override is a zod-validated string, the
       // user's own tenantId is already TenantId-branded.
@@ -50,6 +67,17 @@ export function makeCollectionSetWrite(collection: ContentCollectionDefinition)
       // someone else's signature.
       const owner = store.scopeOf(event.user);
 
+      const body = sanitizeTemplateBody({
+        kind: collection.kind,
+        contentFormat: event.payload.contentFormat,
+        content: event.payload.content,
+      });
+      if (!body.ok) {
+        return writeFailure(
+          new ValidationError({ fields: documentViolationsToFieldIssues(body.violations) }),
+        );
+      }
+
       const existing = await fetchOne<CollectionEntryRow>(db, store.table, {
         tenantId,
         slug: event.payload.slug,
@@ -68,7 +96,7 @@ export function makeCollectionSetWrite(collection: ContentCollectionDefinition)
             // the template upserts put on the row.
             changes: {
               title: event.payload.title,
-              content: event.payload.content,
+              content: body.content,
               contentFormat: event.payload.contentFormat,
               folder: event.payload.folder ?? null,
             },
@@ -91,7 +119,7 @@ export function makeCollectionSetWrite(collection: ContentCollectionDefinition)
           kind: collection.kind,
           locale: event.payload.locale,
           title: event.payload.title,
-          content: event.payload.content,
+          content: body.content,
           contentFormat: event.payload.contentFormat,
           folder: event.payload.folder ?? null,
           ...store.createDefaults(tenantId),

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

@@ -0,0 +1,142 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  defineWriteHandler,
+  type HandlerContext,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  AccessDeniedError,
+  NotFoundError,
+  ValidationError,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
+import * as z from "zod";
+import { requireForTenant } from "../../shared/index.js";
+import { CONTENT_FORMATS } from "../constants.js";
+import { parseLinkedResourceEntries } from "../linked-resources.js";
+import { TemplateResolverErrors } from "../qualified-names.js";
+import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
+import { attachTemplateResources } from "../template-resources.js";
+import { resolveTemplateVariables } from "../template-validation.js";
+import { targetExistsIssue } from "./bundle-import.js";
+import { kindSchema, localeSchema, templateSlugSchema } from "./shared.js";
+import { parseStoredJson, storedRecord } from "./template-gates.js";
+import { refuseTenantScopeUnderSystemTenant, writeTemplateRow } from "./template-write.js";
+
+type CopyScope = "tenant" | "system";
+type WriteCtx = HandlerContext;
+
+function readDbFor(ctx: WriteCtx, scope: CopyScope) {
+  return scope === "system" ? requireForTenant(ctx, SYSTEM_TENANT_ID).db : ctx.db;
+}
+
+// A tenant copy may start from the system default; a system copy only from system rows.
+async function findCopySource(
+  ctx: WriteCtx,
+  where: {
+    scope: CopyScope;
+    tenantId: string;
+    slug: string;
+    kind: string;
+    locale: string;
+  },
+) {
+  const { scope, tenantId, slug, kind, locale } = where;
+  const readDb = readDbFor(ctx, scope);
+  const own = await fetchOne<TemplateResourceRow>(readDb, templateResourcesTable, {
+    tenantId,
+    slug,
+    kind,
+    locale,
+  });
+  if (own || scope === "system") return own;
+  return fetchOne<TemplateResourceRow>(readDb, templateResourcesTable, {
+    tenantId: SYSTEM_TENANT_ID,
+    slug,
+    kind,
+    locale,
+    status: "active",
+  });
+}
+
+export const copyLocaleWrite = defineWriteHandler({
+  name: "copy-locale",
+  schema: z.object({
+    slug: templateSlugSchema,
+    kind: kindSchema,
+    fromLocale: localeSchema,
+    toLocale: localeSchema,
+    overwrite: z.boolean().default(false),
+    /** "system" copies between system-default rows; SystemAdmin only. */
+    scope: z.enum(["tenant", "system"]).default("tenant"),
+  }),
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  description:
+    "Copies the text of one locale of a template into another locale as a draft override of the caller's tenant, taking the tenant's own row or else the system default as the source; use it as the starting point for a translation. It refuses an existing target unless overwrite is set. With scope system (SystemAdmin only) both source and target are system-default rows and the target lands as a system draft; any other caller gets a 403.",
+  handler: async (event, ctx) => {
+    const { slug, kind, fromLocale, toLocale, overwrite, scope } = event.payload;
+    if (scope === "system" && !event.user.roles.includes("SystemAdmin")) {
+      return writeFailure(
+        new AccessDeniedError({
+          i18nKey: "errors.access.denied",
+          details: { reason: TemplateResolverErrors.systemAdminRequired },
+        }),
+      );
+    }
+    const tenantId = scope === "system" ? SYSTEM_TENANT_ID : event.user.tenantId;
+    const refused = refuseTenantScopeUnderSystemTenant(scope, tenantId);
+    if (refused !== null) return refused;
+
+    const readDb = readDbFor(ctx, scope);
+    const source = await findCopySource(ctx, { scope, tenantId, slug, kind, locale: fromLocale });
+    if (!source || !isOneOf(CONTENT_FORMATS, source.contentFormat)) {
+      return writeFailure(new NotFoundError("template-resource", `${slug}/${fromLocale}`));
+    }
+
+    if (!overwrite) {
+      const target = await fetchOne<TemplateResourceRow>(readDb, templateResourcesTable, {
+        tenantId,
+        slug,
+        kind,
+        locale: toLocale,
+      });
+      if (target) {
+        return writeFailure(new ValidationError({ fields: [targetExistsIssue(toLocale)] }));
+      }
+    }
+
+    const variableSchema = storedRecord(source.variableSchema);
+    const written = await writeTemplateRow({
+      ctx,
+      user: event.user,
+      tenantId,
+      scope,
+      status: "draft",
+      variables: resolveTemplateVariables(ctx.registry, slug, variableSchema),
+      payload: {
+        slug,
+        kind,
+        locale: toLocale,
+        content: source.content,
+        contentFormat: source.contentFormat,
+        variableSchema,
+        meta: parseStoredJson(source.meta),
+        title: source.title,
+        folder: source.folder,
+      },
+    });
+    if (!written.isSuccess) return written;
+    // A system source carries no files of its own: its resource keys are known to the tenant row anyway.
+    if (source.tenantId === tenantId) {
+      const attached = await attachTemplateResources(ctx, {
+        user: event.user,
+        tenantId,
+        templateId: written.data.id,
+        resources: parseLinkedResourceEntries(source.linkedResources),
+      });
+      if (!attached.isSuccess) return attached;
+    }
+    return written;
+  },
+});

package/packages/bundled-features/src/template-resolver/handlers/diff-to-system.query.ts

@@ -0,0 +1,72 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineQueryHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
+import { diffTemplateBlocks, splitTemplateBlocks } from "../template-diff.js";
+
+function parseStoredMeta(raw: string | null): Readonly<Record<string, unknown>> {
+  if (raw === null) return {};
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+      ? Object.fromEntries(Object.entries(parsed))
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+function diffMeta(
+  system: Readonly<Record<string, unknown>>,
+  tenant: Readonly<Record<string, unknown>>,
+) {
+  const keys = [...new Set([...Object.keys(system), ...Object.keys(tenant)])].sort();
+  return keys
+    .filter((key) => JSON.stringify(system[key]) !== JSON.stringify(tenant[key]))
+    .map((key) => ({ key, tenant: tenant[key], system: system[key] }));
+}
+
+export const diffToSystemQuery = defineQueryHandler({
+  name: "diff-to-system",
+  schema: z.object({ id: z.string().min(1) }),
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  description:
+    "Compares one tenant override with the system template of the same slug, kind and locale block by block and lists the changed meta settings; use it to show what an override changes before resetting it to the system version.",
+  handler: async (query, ctx) => {
+    const tenantRow = await fetchOne<TemplateResourceRow>(ctx.db, templateResourcesTable, {
+      id: query.payload.id,
+    });
+    if (!tenantRow || tenantRow.tenantId !== query.user.tenantId || tenantRow.scope !== "tenant") {
+      throw new NotFoundError("template-resource", query.payload.id);
+    }
+    const systemRow = await fetchOne<TemplateResourceRow>(ctx.db, templateResourcesTable, {
+      tenantId: SYSTEM_TENANT_ID,
+      slug: tenantRow.slug,
+      kind: tenantRow.kind,
+      locale: tenantRow.locale,
+    });
+    if (!systemRow) throw new NotFoundError("template-resource", tenantRow.slug);
+
+    const blocks = diffTemplateBlocks(
+      splitTemplateBlocks(systemRow.content ?? "", systemRow.contentFormat),
+      splitTemplateBlocks(tenantRow.content ?? "", tenantRow.contentFormat),
+    );
+    const meta = diffMeta(parseStoredMeta(systemRow.meta), parseStoredMeta(tenantRow.meta));
+    return {
+      tenant: {
+        templateId: String(tenantRow.id),
+        templateVersion: tenantRow.version,
+        contentFormat: tenantRow.contentFormat,
+      },
+      system: {
+        templateId: String(systemRow.id),
+        templateVersion: systemRow.version,
+        contentFormat: systemRow.contentFormat,
+      },
+      identical: meta.length === 0 && blocks.every((block) => block.change === "same"),
+      blocks,
+      meta,
+    };
+  },
+});

package/packages/bundled-features/src/template-resolver/handlers/export-bundle.query.ts

@@ -0,0 +1,83 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineQueryHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import {
+  isFileAttachmentEntry,
+  isPdfAttachmentLink,
+  type LinkedResourceEntry,
+  parseLinkedResourceEntries,
+} from "../linked-resources.js";
+import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
+import type { TemplateBundle } from "../template-bundle.js";
+import { readTemplateResource } from "../template-resources.js";
+import { kindSchema, templateSlugSchema } from "./shared.js";
+import { parseStoredJson, storedRecord } from "./template-gates.js";
+
+export const exportBundleQuery = defineQueryHandler({
+  name: "export-bundle",
+  schema: z.object({
+    slug: templateSlugSchema,
+    kind: kindSchema,
+    scope: z.enum(["tenant", "system"]).default("tenant"),
+  }),
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  description:
+    "Exports every locale of one template (the caller's own rows, or the active system rows) together with its linked resource files as a self-contained bundle that import-bundle can read back, for example to move a template between tenants or environments.",
+  handler: async (query, ctx) => {
+    const { slug, kind, scope } = query.payload;
+    const found = await selectMany<TemplateResourceRow>(
+      ctx.db,
+      templateResourcesTable,
+      scope === "system"
+        ? { tenantId: SYSTEM_TENANT_ID, slug, kind, scope: "system", status: "active" }
+        : { tenantId: query.user.tenantId, slug, kind, scope: "tenant" },
+    );
+    const rows = found
+      .filter((row) => row.status !== "archived")
+      .sort((a, b) => a.locale.localeCompare(b.locale));
+    const first = rows[0];
+    if (!first) throw new NotFoundError("template-resource", slug);
+
+    const locales: Record<string, { body: string; meta?: unknown }> = {};
+    const entryByKey = new Map<string, LinkedResourceEntry>();
+    for (const row of rows) {
+      const meta = parseStoredJson(row.meta);
+      locales[row.locale] = { body: row.content ?? "", ...(meta === undefined ? {} : { meta }) };
+      for (const [key, entry] of Object.entries(parseLinkedResourceEntries(row.linkedResources))) {
+        if (!entryByKey.has(key)) entryByKey.set(key, entry);
+      }
+    }
+
+    const resources: TemplateBundle["resources"] = {};
+    const pdfAttachments: TemplateBundle["pdfAttachments"] = {};
+    for (const [key, entry] of entryByKey) {
+      if (isPdfAttachmentLink(entry)) {
+        pdfAttachments[key] = { templateSlug: entry.templateSlug, fileName: entry.fileName };
+        continue;
+      }
+      const attachment = isFileAttachmentEntry(entry);
+      const file = await readTemplateResource(
+        { db: ctx.db, files: ctx.files, user: query.user },
+        attachment ? entry.fileRefId : entry,
+      );
+      if (!file) throw new NotFoundError("template-resource-file", key);
+      resources[key] = {
+        fileName: attachment ? entry.fileName : file.fileName,
+        contentType: file.contentType,
+        base64: Buffer.from(file.bytes).toString("base64"),
+        ...(attachment && { purpose: "attachment" as const }),
+      };
+    }
+
+    return {
+      slug,
+      kind,
+      contentFormat: first.contentFormat,
+      variableSchema: storedRecord(first.variableSchema),
+      locales,
+      resources,
+      pdfAttachments,
+    };
+  },
+});

package/packages/bundled-features/src/template-resolver/handlers/find-by-id.query.ts

@@ -6,7 +6,7 @@ import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
 // Admin-Lookup für UI-Edit-Flow. Returnt das raw Template inkl. draft/
 // archived Status. Tenant-Isolation: User sieht nur Templates des
 // eigenen Tenants oder SYSTEM_TENANT (system-defaults sind public-
-// readable). SystemAdmin sieht alle. Anonymous bleibt aus — Public-
+// readable); ctx.db is tenant-scoped for every role, so the check below is defense in depth. Anonymous bleibt aus — Public-
 // Read geht über resolveTemplate aus der API, nicht hier.
 export const findByIdQuery = defineQueryHandler({
   name: "find-by-id",
@@ -19,10 +19,9 @@ export const findByIdQuery = defineQueryHandler({
       id: query.payload.id,
     });
     if (!row) return null;
-    const isSystemAdmin = query.user.roles.includes("SystemAdmin");
     const isOwnTenant = row.tenantId === query.user.tenantId;
     const isSystemTemplate = row.scope === "system";
-    if (!isSystemAdmin && !isOwnTenant && !isSystemTemplate) return null;
+    if (!isOwnTenant && !isSystemTemplate) return null;
 
     return {
       id: String(row.id),
@@ -35,6 +34,7 @@ export const findByIdQuery = defineQueryHandler({
       contentFormat: row.contentFormat,
       variableSchema: row.variableSchema,
       linkedResources: row.linkedResources,
+      meta: row.meta,
       scope: row.scope,
       parentTemplateId: row.parentTemplateId,
       status: row.status,

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

@@ -0,0 +1,42 @@
+import { defineWriteHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { ValidationError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { templateBundleSchema } from "../template-bundle.js";
+import { importTemplateBundle } from "./bundle-import.js";
+
+export const importBundleSystemWrite = defineWriteHandler({
+  name: "import-bundle-system",
+  schema: z.object({ bundle: templateBundleSchema }),
+  access: { roles: ["SystemAdmin"] },
+  // A system template change reaches every tenant without an override.
+  agent: { risk: "high" as const },
+  description:
+    "Imports a template bundle as system-default templates, active straight away and overwriting existing system rows; SystemAdmin only. Bundles with resource files need a caller in the system tenant, because the files are stored in the caller's file space.",
+  handler: (event, ctx) => {
+    const { bundle } = event.payload;
+    if (Object.keys(bundle.resources).length > 0 && event.user.tenantId !== SYSTEM_TENANT_ID) {
+      return Promise.resolve(
+        writeFailure(
+          new ValidationError({
+            fields: [
+              {
+                path: "bundle.resources",
+                code: "system_resources_need_system_tenant",
+                i18nKey: "templateResolver.errors.template.systemResourcesNeedSystemTenant",
+              },
+            ],
+          }),
+        ),
+      );
+    }
+    return importTemplateBundle({
+      ctx,
+      user: event.user,
+      tenantId: SYSTEM_TENANT_ID,
+      scope: "system",
+      status: "active",
+      bundle,
+      overwrite: true,
+    });
+  },
+});

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

@@ -0,0 +1,22 @@
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { templateBundleSchema } from "../template-bundle.js";
+import { importTemplateBundle } from "./bundle-import.js";
+
+export const importBundleWrite = defineWriteHandler({
+  name: "import-bundle",
+  schema: z.object({ bundle: templateBundleSchema, overwrite: z.boolean().default(false) }),
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  description:
+    "Imports a template bundle (all locales plus resource files, as produced by export-bundle) into the caller's tenant as drafts; it refuses a locale that already has an override unless overwrite is set, and publish makes the drafts live.",
+  handler: (event, ctx) =>
+    importTemplateBundle({
+      ctx,
+      user: event.user,
+      tenantId: event.user.tenantId,
+      scope: "tenant",
+      status: "draft",
+      bundle: event.payload.bundle,
+      overwrite: event.payload.overwrite,
+    }),
+});

package/packages/bundled-features/src/template-resolver/handlers/layout-source.query.ts

@@ -0,0 +1,108 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { FALLBACK_LOCALE } from "../constants.js";
+import { type LayoutRegions, readLayoutRegions } from "../layout-regions.js";
+import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
+import { localeSchema, templateSlugSchema } from "./shared.js";
+
+export type LayoutSourceRow = {
+  readonly id: string;
+  readonly version: number;
+  readonly status: string;
+  readonly locale: string;
+};
+
+export type LayoutSourceResponse = {
+  readonly tenant: LayoutSourceRow | null;
+  readonly system: (LayoutSourceRow & { readonly contentFormat: string }) | null;
+  readonly regions: LayoutRegions;
+  readonly effectiveFormat: "html" | "mjml" | null;
+  readonly mjmlSource: string | null;
+  readonly locale: string;
+};
+
+const EMPTY_REGIONS: LayoutRegions = { header: "", signature: "", footer: "" };
+
+function pickByLocale(
+  rows: readonly TemplateResourceRow[],
+  requested: string | undefined,
+): TemplateResourceRow | null {
+  const live = rows.filter((row) => row.status !== "archived");
+  const candidates = live.length > 0 ? live : rows;
+  return (
+    candidates.find((row) => row.locale === requested) ??
+    candidates.find((row) => row.locale === FALLBACK_LOCALE) ??
+    candidates[0] ??
+    null
+  );
+}
+
+function toSourceRow(row: TemplateResourceRow): LayoutSourceRow {
+  return { id: String(row.id), version: row.version, status: row.status, locale: row.locale };
+}
+
+function layoutFormat(row: TemplateResourceRow): "html" | "mjml" | null {
+  return row.contentFormat === "html" || row.contentFormat === "mjml" ? row.contentFormat : null;
+}
+
+function pickEditedRows(
+  rows: readonly TemplateResourceRow[],
+  isSystemAdmin: boolean,
+  locale: string | undefined,
+): {
+  readonly tenantRow: TemplateResourceRow | null;
+  readonly systemRow: TemplateResourceRow | null;
+} {
+  const tenantRow = isSystemAdmin
+    ? null
+    : pickByLocale(
+        rows.filter((row) => row.scope === "tenant"),
+        locale,
+      );
+  const systemRow = pickByLocale(
+    rows.filter((row) => row.scope === "system"),
+    locale,
+  );
+  return { tenantRow, systemRow };
+}
+
+export const layoutSourceQuery = defineQueryHandler({
+  name: "layout-source",
+  schema: z.object({
+    kind: z.enum(["mail-layout", "pdf-layout"]),
+    slug: templateSlugSchema.default("default"),
+    locale: localeSchema.optional(),
+  }),
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  description:
+    "Reads the layout the caller edits: the tenant's own version and the system version of one layout slug, the header, signature and footer regions of the effective html version, and the locale a save has to use; a SystemAdmin edits the system version and also receives its mjml source. Use it to load the layout editor.",
+  handler: async (query, ctx): Promise<LayoutSourceResponse> => {
+    const { kind, slug, locale } = query.payload;
+    const isSystemAdmin = query.user.roles.includes("SystemAdmin");
+    const rows = await selectMany<TemplateResourceRow>(ctx.db, templateResourcesTable, {
+      kind,
+      slug,
+    });
+    const { tenantRow, systemRow } = pickEditedRows(rows, isSystemAdmin, locale);
+    const effective = tenantRow ?? systemRow;
+    const effectiveFormat = effective === null ? null : layoutFormat(effective);
+    return {
+      tenant: tenantRow === null ? null : toSourceRow(tenantRow),
+      system:
+        systemRow === null
+          ? null
+          : { ...toSourceRow(systemRow), contentFormat: systemRow.contentFormat },
+      regions:
+        effective !== null && effectiveFormat === "html"
+          ? readLayoutRegions(effective.content ?? "")
+          : EMPTY_REGIONS,
+      effectiveFormat,
+      mjmlSource:
+        isSystemAdmin && systemRow !== null && layoutFormat(systemRow) === "mjml"
+          ? (systemRow.content ?? "")
+          : null,
+      locale: effective?.locale ?? locale ?? FALLBACK_LOCALE,
+    };
+  },
+});

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

@@ -4,9 +4,8 @@ import * as z from "zod";
 import { TEMPLATE_KINDS, TEMPLATE_STATUSES } from "../constants.js";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
 
-// List für Admin-UI: filterbar nach kind / locale / status. Liefert
-// system-templates + tenant's eigene zusammen — Admin-UI rendert beide
-// Spalten mit scope-marker. SystemAdmin sieht alle (auch andere Tenants).
+// ctx.db is tenant-scoped even for SystemAdmin: every caller sees its own
+// tenant's rows plus the system defaults, never another tenant's rows.
 export const listQuery = defineQueryHandler({
   name: "list",
   schema: z.object({
@@ -21,10 +20,9 @@ export const listQuery = defineQueryHandler({
   handler: async (query, ctx) => {
     const where: Record<string, unknown> = {};
 
-    // includeSystem=false narrows to own tenant AT THE DB — for non-SystemAdmin
-    // TenantDb permits narrowing within its enforced [own, SYSTEM] scope, for
-    // SystemAdmin (system-scoped db) the where applies verbatim. Filtering at
-    // the DB keeps the limit meaningful (no post-filter starvation).
+    // includeSystem=false narrows to own tenant AT THE DB — TenantDb permits
+    // narrowing within its enforced [own, SYSTEM] scope. Filtering at the DB
+    // keeps the limit meaningful (no post-filter starvation).
     if (!query.payload.includeSystem) {
       where["tenantId"] = query.user.tenantId;
     }