@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/jobs/handlers/trigger.write.ts

@@ -0,0 +1,39 @@
+import type { DbRow } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import type { JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
+import { z } from "zod";
+
+export const triggerWrite = defineWriteHandler({
+  name: "trigger",
+  schema: z.object({
+    jobName: z.string(),
+    payload: z.record(z.string(), z.unknown()).optional(),
+  }),
+  access: { roles: ["SystemAdmin"] },
+  handler: async (event, ctx) => {
+    const registry = ctx.registry;
+    // `jobRunner` is a dynamic context extension — not a core HandlerContext field.
+    const jobRunner = ctx["jobRunner"] as JobRunner;
+
+    const jobDef = registry.getJob(event.payload.jobName);
+    if (!jobDef) {
+      return writeFailure(
+        new NotFoundError("job", event.payload.jobName, {
+          i18nKey: "jobs.errors.unknownJob",
+        }),
+      );
+    }
+
+    const payload = (event.payload.payload ?? {}) as DbRow;
+    const bullJobId = await jobRunner.dispatch(event.payload.jobName, payload, {
+      triggeredById: event.user.id,
+      payload: JSON.stringify(payload),
+    });
+
+    return {
+      isSuccess: true,
+      data: { jobName: event.payload.jobName, bullJobId },
+    };
+  },
+});

package/src/jobs/index.ts

@@ -0,0 +1,5 @@
+export { createJobsFeature } from "./feature";
+export type { JobRunLoggerCallbacks } from "./job-run-logger";
+export { createJobRunLogger } from "./job-run-logger";
+export type { JobLogLevel, JobRunStatus } from "./job-run-table";
+export { jobRunLogsTable, jobRunsTable } from "./job-run-table";

package/src/jobs/job-run-logger.ts

@@ -0,0 +1,213 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { type Registry, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { append, getStreamVersion } from "@cosmicdrift/kumiko-framework/event-store";
+import type { JobLogEntry, JobMeta, JobRunnerOptions } from "@cosmicdrift/kumiko-framework/jobs";
+import { runProjectionsForEvent } from "@cosmicdrift/kumiko-framework/pipeline";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import { eq } from "drizzle-orm";
+import { runCompletedSchema, runFailedSchema, runStartedSchema } from "./events";
+import { jobRunsTable } from "./job-run-table";
+
+// ES job-run lifecycle:
+//   - onJobStart  → jobs:event:run-started   (first append, version 0→1)
+//   - onJobComplete → jobs:event:run-completed (append at current version,
+//                     payload carries the batched logs)
+//   - onJobFailed   → jobs:event:run-failed    (same shape as completed + error)
+//
+// BullMQ callbacks don't carry a tenantId (jobs are cross-tenant). We
+// anchor every run on SYSTEM_TENANT_ID — mirrors how config system-scope
+// rows use the sentinel. The stream still works per-run because
+// aggregate_id is a fresh UUID per run.
+
+export const JOB_RUN_STARTED_EVENT = "jobs:event:run-started" as const;
+export const JOB_RUN_COMPLETED_EVENT = "jobs:event:run-completed" as const;
+export const JOB_RUN_FAILED_EVENT = "jobs:event:run-failed" as const;
+
+export type JobRunLoggerOptions = {
+  readonly db: DbConnection;
+  readonly registry: Registry;
+};
+
+export type JobRunLoggerCallbacks = Pick<
+  JobRunnerOptions,
+  "onJobStart" | "onJobComplete" | "onJobFailed"
+>;
+
+// Default cap on the bullJobId → runId cache. A worker that starts jobs
+// without ever seeing complete/failed callbacks (e.g. crashes mid-run)
+// would otherwise leak entries indefinitely. 10k fits ~1 hour of
+// high-throughput jobs; past that we evict oldest. DB-lookup recovers
+// evicted entries, so correctness isn't at stake — only memory bounds.
+const DEFAULT_CACHE_MAX_ENTRIES = 10_000;
+// Entry TTL. A run that hangs longer than this is either a real stuck
+// worker (ops should alert) or a test-environment run that never fired
+// complete/failed; either way the cache entry has no value. Falls back
+// to DB-lookup if actually needed.
+const DEFAULT_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+
+export function createJobRunLogger(opts: JobRunLoggerOptions): JobRunLoggerCallbacks {
+  const { db, registry } = opts;
+
+  // bullJobId → aggregate uuid. BullMQ hands us the bullJobId on every
+  // callback, but our aggregate stream is keyed by a fresh UUID we mint
+  // on start. The cache threads that UUID from onJobStart through to
+  // onJobComplete/onJobFailed so the completion-event lands on the same
+  // stream as the start-event.
+  //
+  // Bounded cache (LRU-ish with TTL) — worker-crash between start and
+  // complete would otherwise leak entries. DB-lookup recovers evicted
+  // entries via bull_job_id on the projection.
+  type CacheEntry = { readonly runId: string; readonly expiresAt: number };
+  const runIdByBullJobId = new Map<string, CacheEntry>();
+
+  function cachePut(bullJobId: string, runId: string): void {
+    // Enforce max-size BEFORE insert. Map iteration returns insertion
+    // order, so dropping the first entry is the oldest.
+    if (runIdByBullJobId.size >= DEFAULT_CACHE_MAX_ENTRIES) {
+      const oldest = runIdByBullJobId.keys().next().value;
+      if (oldest !== undefined) runIdByBullJobId.delete(oldest);
+    }
+    runIdByBullJobId.set(bullJobId, {
+      runId,
+      expiresAt: Date.now() + DEFAULT_CACHE_TTL_MS,
+    });
+  }
+
+  function cacheGet(bullJobId: string): string | undefined {
+    const entry = runIdByBullJobId.get(bullJobId);
+    if (!entry) return undefined;
+    if (Date.now() >= entry.expiresAt) {
+      runIdByBullJobId.delete(bullJobId); // immediate cleanup on terminal callback
+      return undefined;
+    }
+    return entry.runId;
+  }
+
+  async function resolveRunId(bullJobId: string): Promise<string | undefined> {
+    const cached = cacheGet(bullJobId);
+    if (cached) return cached;
+    const [row] = await db
+      .select({ id: jobRunsTable.id })
+      .from(jobRunsTable)
+      .where(eq(jobRunsTable.bullJobId, bullJobId));
+    // buildBaseColumns's signature types `id` as `string | number` because
+    // it returns both branches of the idType union. We know this table
+    // was built with idType: "uuid" (see job-run-table.ts), so narrowing
+    // via String() is safe runtime-wise. A proper framework-level fix
+    // would overload buildBaseColumns per idType — scoped out of this
+    // follow-up as its return type has four branches (with/without
+    // softDelete × serial/uuid).
+    const id = row ? String(row.id) : undefined;
+    if (id) cachePut(bullJobId, id);
+    return id;
+  }
+
+  return {
+    onJobStart: async (jobName: string, bullJobId: string, meta: JobMeta) => {
+      const runId = generateId();
+      cachePut(bullJobId, runId);
+      // Parse against the registered schema so out-of-dispatcher writes
+      // get the same validation guarantee as ctx.appendEvent. A shape
+      // drift between feature + logger fails loudly at the source
+      // instead of silently landing on the events-table.
+      const payload = runStartedSchema.parse({
+        jobName,
+        bullJobId,
+        status: "running",
+        payload: meta.payload ?? null,
+        triggeredById: meta.triggeredById ?? null,
+        startedAt: Temporal.Now.instant().toString(),
+        attempt: meta.attempt ?? 1,
+      });
+      const event = await append(db, {
+        aggregateId: runId,
+        aggregateType: "jobRun",
+        tenantId: SYSTEM_TENANT_ID,
+        expectedVersion: 0,
+        type: JOB_RUN_STARTED_EVENT,
+        payload,
+        metadata: { userId: "system" },
+      });
+      await runProjectionsForEvent(event, registry, db);
+    },
+
+    onJobComplete: async (
+      _jobName: string,
+      bullJobId: string,
+      duration: number,
+      logs: JobLogEntry[],
+    ) => {
+      const runId = await resolveRunId(bullJobId);
+      // skip: state loss between start + complete (worker restart, cache
+      // evicted AND DB has no matching bull_job_id). Rare edge case; we
+      // drop the completion event rather than forging a jobRun aggregate
+      // from scratch — forensics still has the original BullMQ lifecycle.
+      if (!runId) return;
+      const currentVersion = await getStreamVersion(db, runId, SYSTEM_TENANT_ID);
+      const payload = runCompletedSchema.parse({
+        duration,
+        finishedAt: Temporal.Now.instant().toString(),
+        logs: logs.map((l) => ({
+          level: l.level,
+          message: l.message,
+          timestamp: l.timestamp.toString(),
+        })),
+      });
+      const event = await append(db, {
+        aggregateId: runId,
+        aggregateType: "jobRun",
+        tenantId: SYSTEM_TENANT_ID,
+        expectedVersion: currentVersion,
+        type: JOB_RUN_COMPLETED_EVENT,
+        payload,
+        metadata: { userId: "system" },
+      });
+      await runProjectionsForEvent(event, registry, db);
+      runIdByBullJobId.delete(bullJobId); // immediate cleanup on terminal callback
+    },
+
+    onJobFailed: async (
+      _jobName: string,
+      bullJobId: string,
+      error: string,
+      logs: JobLogEntry[],
+    ) => {
+      const runId = await resolveRunId(bullJobId);
+      // skip: same rare state-loss case as in onJobComplete — drop the
+      // failure event rather than forge a jobRun aggregate from scratch.
+      if (!runId) return;
+      const currentVersion = await getStreamVersion(db, runId, SYSTEM_TENANT_ID);
+      // Read started_at off the projection so we can compute duration
+      // symmetrically to onJobComplete (which gets duration from the
+      // worker). The projection already has started_at from the
+      // run-started inline-apply.
+      const [row] = await db
+        .select({ startedAt: jobRunsTable.startedAt })
+        .from(jobRunsTable)
+        .where(eq(jobRunsTable.id, runId));
+      const now = Temporal.Now.instant();
+      const duration = row ? Number(now.since(row.startedAt).total({ unit: "millisecond" })) : 0;
+      const payload = runFailedSchema.parse({
+        duration,
+        finishedAt: now.toString(),
+        error,
+        logs: logs.map((l) => ({
+          level: l.level,
+          message: l.message,
+          timestamp: l.timestamp.toString(),
+        })),
+      });
+      const event = await append(db, {
+        aggregateId: runId,
+        aggregateType: "jobRun",
+        tenantId: SYSTEM_TENANT_ID,
+        expectedVersion: currentVersion,
+        type: JOB_RUN_FAILED_EVENT,
+        payload,
+        metadata: { userId: "system" },
+      });
+      await runProjectionsForEvent(event, registry, db);
+      runIdByBullJobId.delete(bullJobId); // immediate cleanup on terminal callback
+    },
+  };
+}

package/src/jobs/job-run-table.ts

@@ -0,0 +1,55 @@
+import {
+  buildBaseColumns,
+  instant,
+  integer,
+  table as pgTable,
+  serial,
+  text,
+} from "@cosmicdrift/kumiko-framework/db";
+
+export type JobRunStatus = "queued" | "running" | "completed" | "failed";
+export type JobLogLevel = "info" | "warn" | "error";
+
+// jobRun is a system-scoped events-only aggregate: every job execution is
+// its own stream, driven entirely by BullMQ-callbacks (onJobStart /
+// -Complete / -Failed) via the low-level append() path. Three domain-
+// events cover the lifecycle:
+//   - `jobs:event:run-started`   (when BullMQ picks a job off its queue)
+//   - `jobs:event:run-completed` (duration + batched log entries)
+//   - `jobs:event:run-failed`    (error + duration + batched log entries)
+//
+// Logs ride the completed/failed event as an array — "Option B" from the
+// design discussion: one event per run instead of N events per log line,
+// no log duplication across status transitions. The inline projection
+// expands the batch into N rows in jobRunLogsTable, keeping the pre-ES
+// detail-query-shape intact.
+//
+// No r.entity is registered for `jobRun` — the boot-validator accepts
+// events-only projection sources where every apply-key is a registered
+// domain-event (see registry.ts).
+export const jobRunsTable = pgTable("read_job_runs", {
+  ...buildBaseColumns(false, "uuid"),
+  jobName: text("job_name").notNull(),
+  bullJobId: text("bull_job_id").notNull(),
+  status: text("status").notNull().$type<JobRunStatus>(),
+  payload: text("payload"),
+  error: text("error"),
+  attempt: integer("attempt").default(1).notNull(),
+  startedAt: instant("started_at").notNull(),
+  finishedAt: instant("finished_at"),
+  duration: integer("duration"),
+  triggeredById: text("triggered_by_id"),
+});
+
+// Child projection keyed by the jobRun aggregate id. Pre-ES used a serial
+// PK + integer runId; post-ES runId is still exposed but now holds the
+// uuid of the parent jobRun. Existing detail-query callers treat it as an
+// opaque identifier, so the type-switch is backward-compatible at the
+// query surface.
+export const jobRunLogsTable = pgTable("read_job_run_logs", {
+  id: serial("id").primaryKey(),
+  runId: text("run_id").notNull(),
+  level: text("level").notNull().$type<JobLogLevel>(),
+  message: text("message").notNull(),
+  timestamp: instant("timestamp").notNull(),
+});

package/src/legal-pages/README.md

@@ -0,0 +1,195 @@
+# legal-pages
+
+Opt-in wrapper around [`text-content`](../text-content/) for
+DACH compliance. Ships four fixed public HTML routes
+(`/legal/impressum`, `/legal/datenschutz`, `/legal/imprint`,
+`/legal/privacy`) with Markdown→HTML rendering and a boot check that
+hard-fails in production when the DE required blocks aren't seeded.
+
+**Opt-in.** Internal tools, US apps without an imprint requirement,
+or hobby projects without public access simply don't activate the
+feature.
+
+---
+
+## Setup
+
+```typescript
+import { createLegalPagesFeature } from "@cosmicdrift/kumiko-bundled-features/legal-pages";
+import {
+  createTextContentApi,
+  createTextContentFeature,
+} from "@cosmicdrift/kumiko-bundled-features/text-content";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+
+runProdApp({
+  features: [
+    createTextContentFeature(),  // legal-pages requires text-content
+    createLegalPagesFeature(),
+    /* ... */
+  ],
+  // Two wirings are required:
+  //   1. anonymousAccess for /legal/* routes (run without a JWT)
+  //   2. extraContext.textContent for the boot check (cross-feature
+  //      decoupling — legal-pages imports no code from text-content,
+  //      only uses the API via ctx)
+  anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID },
+  extraContext: ({ db }) => ({
+    textContent: createTextContentApi(db),
+  }),
+});
+```
+
+---
+
+### Production table setup
+
+legal-pages doesn't have its own table — it uses text-content's
+`read_text_blocks`. Table setup therefore goes through text-content:
+
+```bash
+yarn kumiko migrate generate    # text-block entity is detected
+yarn kumiko migrate apply
+```
+
+See [text-content/README.md](../text-content/README.md#production-table-setup).
+
+## Routes
+
+| Path | Slug + lang | Title fallback (when block empty) |
+|---|---|---|
+| `GET /legal/impressum` | `imprint` / `de` | "Impressum" |
+| `GET /legal/datenschutz` | `privacy` / `de` | "Datenschutzerklärung" |
+| `GET /legal/imprint` | `imprint` / `en` | "Imprint" |
+| `GET /legal/privacy` | `privacy` / `en` | "Privacy Policy" |
+
+Response:
+- `200 text/html` — block exists + has body. Cache header `public, max-age=300`.
+- `404 text/plain` — block missing. Hint: "Tenant admin must set this text block".
+- `503 text/plain` — `app.fetch` to `/api/query` failed (anonymousAccess missing?).
+
+Layout: a minimal HTML5 skeleton with inline CSS — apps that want to
+integrate into their own layout use `text-content:query:by-slug`
+directly and render themselves.
+
+---
+
+## Boot check
+
+`r.job` with `runOnBoot: true` checks at app start whether the DE
+required blocks exist in SYSTEM_TENANT:
+
+| Slug + lang | What happens when missing |
+|---|---|
+| `imprint` / `de` | **Production:** `throw new Error(...)` blocks app start. **Dev:** `ctx.log.warn(...)` |
+| `privacy` / `de` | as above |
+
+EN versions are **not** boot-fail-relevant (`LEGAL_OPTIONAL_BLOCKS`).
+Routes return `404` if an EN block is missing.
+
+→ Apps that activate the feature must seed both DE blocks before a
+production deploy — either via a bootstrap script (`seedTextBlock`) or
+manually via the TenantAdmin API.
+
+---
+
+## TenantAdmin maintenance via the API
+
+Tenant admins (or platform SystemAdmin for SYSTEM_TENANT texts) can
+update content at any time through the standard write handler:
+
+```typescript
+// From the tenant admin frontend (or admin curl):
+await fetch("/api/write", {
+  method: "POST",
+  headers: { "Content-Type": "application/json", Authorization: `Bearer ${jwt}` },
+  body: JSON.stringify({
+    type: "text-content:write:set",
+    payload: {
+      slug: "imprint",
+      lang: "de",
+      title: "Impressum",
+      body: "## Angaben gemäß § 5 TMG\n\n...",
+    },
+  }),
+});
+```
+
+→ Idempotent: a second call with the same `(slug, lang)` updates the block.
+ACL: `roles: ["TenantAdmin", "SystemAdmin"]` — SystemAdmin (a global
+role) may set SYSTEM_TENANT texts, TenantAdmin only tenant-owned ones.
+
+→ The route's cache header is `public, max-age=300` — after an update,
+visitors see new content within 5 minutes at most. If you need
+instant visibility, you can help things along with a CDN purge.
+
+## Seeding
+
+On first app boot or via migration:
+
+```typescript
+import { seedTextBlock } from "@cosmicdrift/kumiko-bundled-features/text-content/seeding";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+
+await seedTextBlock(db, {
+  tenantId: SYSTEM_TENANT_ID,
+  slug: "imprint",
+  lang: "de",
+  title: "Impressum",
+  body: `## Angaben gemäß § 5 TMG
+
+**Marc Frost**
+
+Slevogtstr. 10
+04159 Leipzig
+
+## Kontakt
+
+E-Mail: hello@example.com`,
+});
+```
+
+Templates for imprint + privacy policy: see
+[docs/plans/datenschutz/legal-artifacts.md](../../../../docs/plans/datenschutz/legal-artifacts.md)
+and vetted external generators (e-recht24.de,
+datenschutz-generator.de).
+
+---
+
+## XSS — currently not secured by design
+
+`marked` renders HTML tags 1:1, so a malicious tenant admin could in
+theory put `<script>` into the body.
+
+Currently accepted because:
+- only `roles: ["TenantAdmin"]` may set texts
+- multi-author setups don't exist yet
+- self-hosted tier without unknown tenant admins
+
+**Phase-2 hardening:** `DOMPurify` or `isomorphic-dompurify`
+sanitization step between `marked.parse()` and the response.
+Documented when a customer with a multi-author setup shows up.
+
+---
+
+## Tenant model
+
+**1 app = X tenants = 1 imprint.** All subdomains/tenant hosts of a
+Kumiko app share the SYSTEM_TENANT version of the legal pages. If you
+need per-tenant imprints (rare — typical case: the platform operator
+is the responsible party, not the tenant customer), call
+text-content's by-slug query directly with a tenant-specific TenantId
+and put your own routes in front.
+
+---
+
+## Architecture cross-refs
+
+- [docs/plans/datenschutz/](../../../../docs/plans/datenschutz/)
+  — consolidated privacy plan index
+- [docs/plans/datenschutz/legal-artifacts.md](../../../../docs/plans/datenschutz/legal-artifacts.md)
+  — templates + where-is-what for imprint/AVV/TOMs/RoPA
+- [docs/plans/datenschutz/compliance-as-product.md](../../../../docs/plans/datenschutz/compliance-as-product.md)
+  — roadmap for auto-generation (sub-processor list, TOMs, data-breach workflow)
+- [samples/recipes/legal-pages/](../../../../samples/recipes/legal-pages/)
+  — live sample with both features wired up