@cosmicdrift/kumiko-bundled-features 0.328.0 → 0.329.0

package/dist/jobs/handlers/reindex-entity.job.js

@@ -0,0 +1,46 @@
+// Manual, perTenant backfill job (#1206/#1215) — indexes existing rows for
+// an entity that only got `searchable: true` after rows already existed.
+// perTenant fan-out (job-runner.ts) also applies to a manual dispatch, not
+// just cron: one `jobs:write:trigger` call with { entity } re-runs once per
+// active tenant.
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { reindexEntity } from "@cosmicdrift/kumiko-framework/search";
+import * as z from "zod";
+export const reindexEntityPayloadSchema = z.object({
+    entity: z.string().min(1),
+});
+export const reindexEntityJob = async (rawPayload, ctx) => {
+    const { entity } = reindexEntityPayloadSchema.parse(rawPayload);
+    if (!ctx.registry) {
+        throw new InternalError({
+            message: "[jobs:reindex-entity] ctx.registry missing — job context requires the registry.",
+        });
+    }
+    if (!ctx.searchAdapter) {
+        throw new InternalError({
+            message: "[jobs:reindex-entity] ctx.searchAdapter missing — mount a search adapter to run this job.",
+        });
+    }
+    // perTenant fan-out — the job-runner enqueues one child run per active
+    // tenant with ctx.systemUser scoped to it; a run without one (e.g.
+    // misconfigured manual dispatch outside the fan-out) has nothing scoped
+    // to reindex. ctx._tenantId is never populated per-dispatch (only
+    // ctx.systemUser is), so it is not a valid fallback here.
+    const tenantId = ctx.systemUser?.tenantId;
+    if (tenantId === undefined) {
+        // skip: fired without a perTenant fan-out tenant — nothing scoped to reindex
+        return;
+    }
+    if (!ctx.systemDb) {
+        throw new InternalError({
+            message: "[jobs:reindex-entity] ctx.systemDb missing — the owning feature must declare r.systemScope().",
+        });
+    }
+    // unsafeRaw bypasses tenant filtering, safe here only because reindexEntity
+    // filters `WHERE tenant_id = $1` itself with this same tenantId.
+    ctx.systemDb.assertTenantMatch(tenantId);
+    const db = ctx.systemDb.unsafeRaw("reindexEntity filters WHERE tenant_id = $1 itself with this job's tenantId");
+    const result = await reindexEntity(db, ctx.registry, ctx.searchAdapter, entity, tenantId);
+    ctx.log?.info?.(`[jobs:reindex-entity] tenant=${tenantId} reindexed ${entity}: ${result.indexedRows}/${result.scannedRows} rows indexed` +
+        `${result.failures.length > 0 ? ` (${result.failures.length} failed)` : ""}`);
+};

package/dist/jobs/handlers/retention-cleanup.job.d.ts

@@ -0,0 +1,3 @@
+import type { JobHandlerFn } from "@cosmicdrift/kumiko-framework/engine";
+export declare const DEFAULT_JOB_RUN_RETENTION_DAYS = 30;
+export declare function createRetentionCleanupJob(retentionDays: number): JobHandlerFn;

package/dist/jobs/handlers/retention-cleanup.job.js

@@ -0,0 +1,16 @@
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { deleteStaleJobRuns } from "../db/queries/retention.js";
+// Single source for the retention window — change here, nowhere else.
+export const DEFAULT_JOB_RUN_RETENTION_DAYS = 30;
+export function createRetentionCleanupJob(retentionDays) {
+    return async (_payload, ctx) => {
+        if (!ctx.systemDb) {
+            throw new InternalError({
+                message: "[jobs:retention-cleanup] ctx.systemDb missing — is r.systemScope() still set on the jobs feature?",
+            });
+        }
+        const db = ctx.systemDb.unsafeRaw("store_job_runs retention purges finished runs of every tenant"); // @cast-boundary db-operator — DbRunner narrows to DbConnection, jobs never run inside a DbTx
+        const result = await deleteStaleJobRuns(db, retentionDays);
+        ctx.log?.info?.(`[jobs:retention-cleanup] complete: ${JSON.stringify(result)}`);
+    };
+}

package/dist/jobs/handlers/retry.write.d.ts

@@ -0,0 +1,8 @@
+import * as z from "zod";
+export declare const retryWrite: import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"retry", z.ZodObject<{
+    runId: z.ZodUUID;
+}, z.core.$strip>, {
+    jobName: string;
+    bullJobId: string;
+    retriedFromRunId: string;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/jobs/handlers/retry.write.js

@@ -0,0 +1,65 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { PII_ERASED_SENTINEL } from "@cosmicdrift/kumiko-framework/crypto";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError, NotFoundError, UnprocessableError, writeFailure, } from "@cosmicdrift/kumiko-framework/errors";
+import { parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
+import * as z from "zod";
+import { decryptStoredPii } from "../../shared/index.js";
+import { JobErrors } from "../constants.js";
+import { jobRunsTable } from "../job-run-table.js";
+export const retryWrite = defineWriteHandler({
+    name: "retry",
+    description: "Re-dispatches a failed job run with its original payload and triggering user; use it to rerun a job that failed for a transient reason.",
+    // Post-ES: runId is the uuid aggregate-id. See detail.query for the
+    // rationale — jobs is framework-ops, callers are admin tooling only.
+    schema: z.object({ runId: z.uuid() }),
+    access: { roles: ["SystemAdmin"] },
+    handler: async (event, ctx) => {
+        if (!ctx.systemDb) {
+            throw new InternalError({
+                message: "jobs:write:retry requires ctx.systemDb (feature must declare r.systemScope())",
+            });
+        }
+        const db = ctx.systemDb.acknowledgeCrossTenant("cross-tenant job monitoring");
+        // @cast-boundary engine-payload — JobRunner attached by app-boot via ctx-extension
+        const jobRunner = ctx["jobRunner"];
+        const run = await fetchOne(db, jobRunsTable, { id: event.payload.runId });
+        if (!run) {
+            return writeFailure(new NotFoundError("jobRun", event.payload.runId, {
+                i18nKey: "jobs.errors.notFound",
+            }));
+        }
+        if (run.status !== "failed") {
+            return writeFailure(new UnprocessableError(JobErrors.onlyFailedCanRetry, {
+                i18nKey: "jobs.errors.onlyFailedCanRetry",
+                details: { status: run.status },
+            }));
+        }
+        // payload is stored encrypted under the triggering user's DEK (#799),
+        // same mechanism as detail.query.ts/list.query.ts — decrypt before
+        // parsing it as JSON. A key erased since the run finished decrypts to
+        // PII_ERASED_SENTINEL, which is not JSON; reject the retry rather than
+        // dispatch it with a silently emptied payload.
+        let payload = {};
+        let decryptedPayloadJson = null;
+        if (run.payload) {
+            const decryptedPayload = await decryptStoredPii(run.payload, "payload", `job run ${event.payload.runId} payload`);
+            if (decryptedPayload === PII_ERASED_SENTINEL) {
+                return writeFailure(new UnprocessableError(JobErrors.payloadErased, {
+                    i18nKey: "jobs.errors.payloadErased",
+                }));
+            }
+            payload = parseJsonOrThrow(decryptedPayload, `job run ${event.payload.runId} payload`);
+            decryptedPayloadJson = decryptedPayload;
+        }
+        // Retry re-uses the original run's DEK owner so the retry's logs/payload stay encrypted.
+        const bullJobId = await jobRunner.dispatch(run.jobName, payload, {
+            triggeredById: run.triggeredById ?? undefined,
+            ...(decryptedPayloadJson !== null && { payload: decryptedPayloadJson }),
+        });
+        return {
+            isSuccess: true,
+            data: { jobName: run.jobName, bullJobId, retriedFromRunId: event.payload.runId },
+        };
+    },
+});

package/dist/jobs/handlers/stale-run-sweep.job.d.ts

@@ -0,0 +1,3 @@
+import type { JobHandlerFn } from "@cosmicdrift/kumiko-framework/engine";
+export declare const DEFAULT_JOB_RUN_STALE_TIMEOUT_HOURS = 24;
+export declare function createStaleRunSweepJob(timeoutHours: number): JobHandlerFn;

package/dist/jobs/handlers/stale-run-sweep.job.js

@@ -0,0 +1,23 @@
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { markStaleJobRunsFailed } from "../db/queries/stale-run-sweep.js";
+// 24h, not e.g. the 1h cache-TTL used elsewhere in this feature (see
+// job-run-logger.ts) — a wrong guess there costs one extra DB lookup, a
+// wrong guess here marks a still-running job "failed" and opens
+// retry.write.ts's retry gate on it while the original run is still
+// executing (concurrent duplicate dispatch). reindexEntity/projectionRebuild
+// (registered in this same feature) can legitimately run for hours, so the
+// default has to clear any plausible real job, not just be "long".
+// Configurable per-app via JobsFeatureOptions.staleRunTimeoutHours.
+export const DEFAULT_JOB_RUN_STALE_TIMEOUT_HOURS = 24;
+export function createStaleRunSweepJob(timeoutHours) {
+    return async (_payload, ctx) => {
+        if (!ctx.systemDb) {
+            throw new InternalError({
+                message: "[jobs:stale-run-sweep] ctx.systemDb missing — is r.systemScope() still set on the jobs feature?",
+            });
+        }
+        const db = ctx.systemDb.unsafeRaw("stale-run sweep marks stuck runs of every tenant as failed"); // @cast-boundary db-operator — DbRunner narrows to DbConnection, jobs never run inside a DbTx
+        const result = await markStaleJobRunsFailed(db, timeoutHours);
+        ctx.log?.info?.(`[jobs:stale-run-sweep] complete: ${JSON.stringify(result)}`);
+    };
+}

package/dist/jobs/handlers/tenant-failures.query.d.ts

@@ -0,0 +1,14 @@
+import * as z from "zod";
+export declare const tenantFailuresQuery: import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"failures", z.ZodObject<{
+    jobName: z.ZodOptional<z.ZodString>;
+    subject: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, {
+    rows: {
+        jobName: string;
+        subject: Record<string, unknown> | null;
+        messageKey: string;
+        failedAt: Temporal.Instant;
+    }[];
+    nextCursor: null;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/jobs/handlers/tenant-failures.query.js

@@ -0,0 +1,70 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
+import * as z from "zod";
+import { tenantJobFailuresTable } from "../tenant-job-failure-table.js";
+const DEFAULT_LIMIT = 50;
+// Mirrors job-runner.ts's jobSubjectKey: sorted field names, so a caller that
+// passes the same subject values gets the same string the writer stored.
+function subjectKey(subject) {
+    return JSON.stringify(Object.keys(subject)
+        .sort()
+        .map((field) => [field, subject[field] ?? null]));
+}
+function isSubjectEntry(value) {
+    return Array.isArray(value) && typeof value[0] === "string";
+}
+function parseSubject(stored) {
+    if (stored === null)
+        return null;
+    // A corrupt subject must not fail the whole list — the record still tells
+    // the tenant which job failed and why. parseJsonSafe only survives a
+    // SyntaxError, so the shape needs its own check.
+    const parsed = parseJsonSafe(stored, null);
+    if (!Array.isArray(parsed))
+        return null;
+    return Object.fromEntries(parsed.filter(isSubjectEntry));
+}
+export const tenantFailuresQuery = defineQueryHandler({
+    name: "failures",
+    description: "Lists the calling tenant's own failed jobs — one record per job and subject, newest first, each carrying a translation key for the reason, never the provider's own error message; use it to tell a tenant that their asynchronous job failed instead of leaving the screen waiting.",
+    schema: z.object({
+        jobName: z.string().optional(),
+        subject: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+        limit: z.number().min(1).max(200).optional(),
+    }),
+    // Every membership rank: a failure record carries a job name and a
+    // translation key, nothing a team member of the tenant may not see.
+    access: { roles: access.roles("User", "Editor", ...access.admin) },
+    handler: async (query, ctx) => {
+        if (!ctx.systemDb) {
+            throw new InternalError({
+                message: "jobs:query:failures requires ctx.systemDb (feature must declare r.systemScope())",
+            });
+        }
+        // assertTenantMatch is a self-check on the caller and returns the same
+        // unfiltered system-mode db (tenant-db.ts) — the explicit tenantId below
+        // is the filter, assertRowsTenant the second net. There is no
+        // cross-tenant mode here: SystemAdmin reads runs via jobs:query:list.
+        const db = ctx.systemDb.assertTenantMatch(query.user.tenantId);
+        const where = { tenantId: [query.user.tenantId] };
+        if (query.payload.jobName)
+            where["jobName"] = query.payload.jobName;
+        if (query.payload.subject)
+            where["subject"] = subjectKey(query.payload.subject);
+        const rows = await selectMany(db, tenantJobFailuresTable, where, {
+            orderBy: { col: "failedAt", direction: "desc" },
+            limit: query.payload.limit ?? DEFAULT_LIMIT,
+        });
+        return {
+            rows: ctx.systemDb.assertRowsTenant(rows, "tenantId").map((row) => ({
+                jobName: row.jobName,
+                subject: parseSubject(row.subject),
+                messageKey: row.messageKey,
+                failedAt: row.failedAt,
+            })),
+            nextCursor: null,
+        };
+    },
+});

package/dist/jobs/handlers/trigger.write.d.ts

@@ -0,0 +1,8 @@
+import * as z from "zod";
+export declare const triggerWrite: import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"trigger", z.ZodObject<{
+    jobName: z.ZodString;
+    payload: z.ZodOptional<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>;
+}, z.core.$strip>, {
+    jobName: string;
+    bullJobId: string;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/jobs/handlers/trigger.write.js

@@ -0,0 +1,63 @@
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError, UnprocessableError, validationErrorFromZod, writeFailure, } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { JobErrors } from "../constants.js";
+import { isManualTrigger } from "../is-manual-trigger.js";
+export const triggerWrite = defineWriteHandler({
+    name: "trigger",
+    description: "Starts one manually-triggerable job with the given payload after validating it against the job's schema; use it to run a maintenance or import job on demand.",
+    schema: z.object({
+        jobName: z.string(),
+        payload: z.union([z.record(z.string(), z.unknown()), z.string()]).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"]; // @cast-boundary dynamic-key
+        const jobDef = registry.getJob(event.payload.jobName);
+        if (!jobDef) {
+            return writeFailure(new NotFoundError("job", event.payload.jobName, {
+                i18nKey: "jobs.errors.unknownJob",
+            }));
+        }
+        if (!isManualTrigger(jobDef.trigger)) {
+            return writeFailure(new UnprocessableError(JobErrors.notManual, {
+                i18nKey: "jobs.errors.notManual",
+                details: { jobName: event.payload.jobName },
+            }));
+        }
+        let rawPayload = {};
+        if (typeof event.payload.payload === "string" && event.payload.payload.trim() !== "") {
+            try {
+                const parsed = JSON.parse(event.payload.payload);
+                if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+                    return writeFailure(new UnprocessableError(JobErrors.notManual));
+                }
+                rawPayload = parsed;
+            }
+            catch {
+                return writeFailure(new UnprocessableError(JobErrors.notManual));
+            }
+        }
+        else if (event.payload.payload !== undefined) {
+            rawPayload = event.payload.payload;
+        }
+        let payload = rawPayload;
+        if (jobDef.schema !== undefined) {
+            const parsed = jobDef.schema.safeParse(rawPayload);
+            if (!parsed.success) {
+                return writeFailure(validationErrorFromZod(parsed.error));
+            }
+            payload = parsed.data;
+        }
+        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/dist/jobs/i18n.d.ts

@@ -0,0 +1,5 @@
+type LocalizedString = {
+    readonly en: string;
+};
+export declare const JOBS_I18N: Readonly<Record<string, LocalizedString>>;
+export {};

package/dist/jobs/i18n.js

@@ -0,0 +1,42 @@
+// @runtime client
+// Server + client i18n for jobs operator screens.
+export const JOBS_I18N = {
+    "screen:job-runs.title": { en: "Job runs" },
+    "screen:job-run-detail.title": { en: "Job run" },
+    "screen:job-trigger.title": { en: "Trigger job" },
+    "jobs:entity:__action-form__:field:jobName": { en: "Job name" },
+    "jobs:entity:__action-form__:field:payload": { en: "JSON payload" },
+    "jobs:nav.jobRuns": { en: "Jobs" },
+    "jobs.runs.open": { en: "Details" },
+    "jobs.runs.filter.status": { en: "Status" },
+    "jobs.runs.filter.completed": { en: "Completed" },
+    "jobs.runs.filter.failed": { en: "Failed" },
+    "jobs.runs.filter.running": { en: "Running" },
+    "jobs.runs.filter.queued": { en: "Queued" },
+    "jobs.runs.col.job": { en: "Job" },
+    "jobs.runs.col.status": { en: "Status" },
+    "jobs.runs.col.started": { en: "Started" },
+    "jobs.runs.col.duration": { en: "Duration (ms)" },
+    "jobs.detail.field.job": { en: "Job" },
+    "jobs.detail.field.status": { en: "Status" },
+    "jobs.detail.field.id": { en: "Run ID" },
+    "jobs.detail.field.started": { en: "Started" },
+    "jobs.detail.field.finished": { en: "Finished" },
+    "jobs.detail.field.duration": { en: "Duration (ms)" },
+    "jobs.detail.field.error": { en: "Error" },
+    "jobs.detail.logs": { en: "Logs" },
+    "jobs.detail.retry": { en: "Retry" },
+    "jobs.trigger.title": { en: "Run a job" },
+    "jobs.trigger.submit": { en: "Run" },
+    "jobs.errors.unknownJob": { en: "Unknown job." },
+    "jobs.errors.notManual": {
+        en: "This job cannot be triggered manually.",
+    },
+    "jobs.errors.notFound": { en: "Not found." },
+    "jobs.errors.onlyFailedCanRetry": {
+        en: "Only failed runs can be retried.",
+    },
+    "jobs.errors.payloadErased": {
+        en: "This run's payload can no longer be read — the triggering user's data was erased.",
+    },
+};

package/dist/jobs/index.d.ts

@@ -0,0 +1,7 @@
+export { JOBS_FEATURE, JobErrors, JobHandlers, JobQueries } from "./constants.js";
+export { createJobsFeature, type JobsFeatureOptions } from "./feature.js";
+export type { JobRunLoggerCallbacks } from "./job-run-logger.js";
+export { createJobRunLogger } from "./job-run-logger.js";
+export type { JobLogLevel, JobRunStatus } from "./job-run-table.js";
+export { jobRunLogsTable, jobRunsTable } from "./job-run-table.js";
+export { tenantJobFailuresTable } from "./tenant-job-failure-table.js";

package/dist/jobs/index.js

@@ -0,0 +1,5 @@
+export { JOBS_FEATURE, JobErrors, JobHandlers, JobQueries } from "./constants.js";
+export { createJobsFeature } from "./feature.js";
+export { createJobRunLogger } from "./job-run-logger.js";
+export { jobRunLogsTable, jobRunsTable } from "./job-run-table.js";
+export { tenantJobFailuresTable } from "./tenant-job-failure-table.js";

package/dist/jobs/is-manual-trigger.d.ts

@@ -0,0 +1,2 @@
+import type { JobDefinition } from "@cosmicdrift/kumiko-framework/engine";
+export declare function isManualTrigger(trigger: JobDefinition["trigger"]): boolean;

package/dist/jobs/is-manual-trigger.js

@@ -0,0 +1,3 @@
+export function isManualTrigger(trigger) {
+    return "manual" in trigger && trigger.manual === true;
+}

package/dist/jobs/job-instant.d.ts

@@ -0,0 +1,2 @@
+import { Temporal } from "temporal-polyfill";
+export declare function parseJobInstant(iso: string): Temporal.Instant;

package/dist/jobs/job-instant.js

@@ -0,0 +1,8 @@
+import { Temporal } from "temporal-polyfill";
+// kumiko-framework#1525: the five value-position Temporal.Instant.from
+// call sites in feature.ts live inside defineApply callbacks with no
+// exported seam, so this thin wrapper gives the ambient-global-independence
+// regression test something to import directly.
+export function parseJobInstant(iso) {
+    return Temporal.Instant.from(iso);
+}

package/dist/jobs/job-run-logger.d.ts

@@ -0,0 +1,10 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { type Registry } from "@cosmicdrift/kumiko-framework/engine";
+import type { JobRunnerOptions } from "@cosmicdrift/kumiko-framework/jobs";
+export type JobRunLoggerOptions = {
+    readonly db: DbConnection;
+    readonly registry: Registry;
+};
+export type JobRunLoggerCallbacks = Pick<JobRunnerOptions, "onJobStart" | "onJobComplete" | "onJobFailed">;
+export declare function encryptFailureError(error: string, triggeredById: string | null): Promise<string>;
+export declare function createJobRunLogger(opts: JobRunLoggerOptions): JobRunLoggerCallbacks;