@cosmicdrift/kumiko-framework 0.146.4 → 0.147.0

package/src/stack/__tests__/setup-test-stack-jobs.integration.test.ts

@@ -0,0 +1,95 @@
+// Regression test for #983 — a write handler calling `ctx["jobRunner"]
+// .dispatch(...)` directly (the documented pattern, e.g. bundled jobs
+// feature's trigger.write.ts) threw `TypeError: undefined is not an
+// object` under both `setupTestStack` and `runDevApp`, because neither
+// built a JobRunner nor merged one into the dispatcher's context.
+//
+// Two things had to be fixed together (see dispatch-shared.ts and
+// test-stack.ts for the respective commits):
+//   1. `setupTestStack({ jobs: {...} })` now builds a real JobRunner and
+//      merges it into dispatcherOptions — this test's `jobs: {}` opt-in.
+//   2. `buildHandlerContext` (packages/framework/src/pipeline/dispatch-
+//      shared.ts) never spread `DispatchContext.jobRunner` into the
+//      handler-facing ctx at all — a gap that predates this issue and
+//      affects the prod entrypoint too, not just dev/test. Fixed there,
+//      not band-aided into `context:` here — otherwise test/dev would
+//      pass while prod's `ctx.jobRunner` stayed undefined.
+//
+// This test drives the manual-dispatch repro from the issue, not the
+// auto-trigger path (already covered by entrypoint-job-wiring.integration
+// .test.ts) — the two paths read from different context slots and a fix
+// for one doesn't guarantee the other.
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { defineFeature } from "../../engine";
+import { InternalError, writeFailure } from "../../errors";
+import { waitFor } from "../../testing";
+import { setupTestStack, type TestStack } from "../test-stack";
+import { TestUsers } from "../test-users";
+
+const jobRuns: Array<{ name: string; payload: Record<string, unknown> }> = [];
+
+const manualDispatchFeature = defineFeature("manualdispatch", (r) => {
+  r.writeHandler(
+    "create",
+    z.object({ note: z.string() }),
+    async (event, ctx) => {
+      // Exact repro from #983: bracket-access, dynamic context extension —
+      // not a typed HandlerContext field (mirrors trigger.write.ts).
+      const jobRunner = ctx["jobRunner"] as
+        | { dispatch: (name: string, payload: Record<string, unknown>) => Promise<string> }
+        | undefined;
+      if (!jobRunner) {
+        return writeFailure(new InternalError({ message: "no jobRunner on ctx" }));
+      }
+      await jobRunner.dispatch("manualdispatch:job:record", { note: event.payload.note });
+      return { isSuccess: true as const, data: { id: 1, note: event.payload.note } };
+    },
+    { access: { openToAll: true } },
+  );
+  r.job("record", { trigger: { manual: true }, runIn: "worker" }, async (payload) => {
+    jobRuns.push({ name: "manualdispatch:job:record", payload });
+  });
+});
+
+let stack: TestStack | undefined;
+
+afterEach(async () => {
+  if (stack) await stack.cleanup();
+  stack = undefined;
+});
+
+describe("setupTestStack({ jobs }) wires ctx.jobRunner for manual dispatch", () => {
+  test("write handler's ctx.jobRunner.dispatch(...) works end-to-end", async () => {
+    jobRuns.length = 0;
+    stack = await setupTestStack({
+      features: [manualDispatchFeature],
+      // consumerLane: this test has no separate consumer (unlike runDevApp's
+      // startDevJobRunners), so it must be the one running the job.
+      jobs: { consumerLane: "worker" },
+    });
+
+    await stack.http.writeOk("manualdispatch:write:create", { note: "hi" }, TestUsers.admin);
+
+    await waitFor(() => {
+      const run = jobRuns.find((e) => e.name === "manualdispatch:job:record");
+      expect(run).toBeDefined();
+      expect(run?.payload["note"]).toBe("hi");
+    });
+  });
+
+  test("without `jobs` opt-in, ctx.jobRunner stays undefined (no-op, not a throw)", async () => {
+    stack = await setupTestStack({ features: [manualDispatchFeature] });
+    expect(stack.jobRunner).toBeUndefined();
+
+    // The handler itself guards against a missing jobRunner (writeFailure,
+    // not a thrown TypeError) — same contract as trigger.write.ts's cast.
+    const err = await stack.http.writeErr(
+      "manualdispatch:write:create",
+      { note: "hi" },
+      TestUsers.admin,
+    );
+    expect(err.code).toBe("internal_error");
+  });
+});

package/src/stack/test-stack.ts

@@ -6,8 +6,9 @@ import { createSseBroker } from "../api/sse-broker";
 import type { PgClient } from "../db/connection";
 import { extractTableInfo } from "../db/query";
 import { createRegistry } from "../engine/registry";
-import type { FeatureDefinition, Registry, TenantId } from "../engine/types";
+import type { FeatureDefinition, JobRunIn, Registry, TenantId } from "../engine/types";
 import { createArchivedStreamsTable, createEventsTable } from "../event-store";
+import { createJobRunner, type JobRunner } from "../jobs";
 import type { Lifecycle } from "../lifecycle";
 import type { ObservabilityProvider } from "../observability";
 import type { Dispatcher, EventDispatcher } from "../pipeline";
@@ -41,6 +42,10 @@ export type TestStack = {
   // Only set when the caller passed `lifecycle` via options. Tests that
   // exercise drain() / /health/ready wire one in; ordinary suites ignore it.
   lifecycle?: Lifecycle;
+  // Only set when `options.jobs` is truthy AND ≥1 `r.job(...)` is
+  // registered in the mounted features. Lets integration tests call
+  // `stack.jobRunner.dispatch(...)` directly, mirroring `ctx.jobRunner`.
+  jobRunner?: JobRunner;
   cleanup: () => Promise<void>;
 };
 
@@ -119,6 +124,23 @@ export type TestStackOptions = {
         sseBroker: import("../api/sse-broker").SseBroker;
         redis: import("ioredis").default;
       }) => import("../api/server").ServerOptions["anonymousAccess"]);
+  /** Opt-in JobRunner wired into ctx.jobRunner (write handlers'
+   *  `ctx.jobRunner.dispatch(...)`) and merged into dispatcherOptions so
+   *  event-triggered jobs enqueue on commit — mirrors the prod entrypoint's
+   *  `buildJobRunnerWithHook`. No-ops when no `r.job(...)` is registered
+   *  anywhere in the mounted features — the bundled `createJobsFeature()`
+   *  (operator UI) is NOT required, matching prod's unconditional build.
+   *  Default `undefined` — enqueuer-only, holds queue-clients for both
+   *  lanes so `ctx.jobRunner.dispatch(...)` routes correctly but starts no
+   *  local consumer/cron-scheduler (avoids double-running `runOnBoot`/cron
+   *  jobs when the caller, e.g. runDevApp, already runs its own consumer
+   *  for that lane). Pass `consumerLane` only when this IS the sole
+   *  consumer (e.g. a test that wants the dispatched job to actually
+   *  execute without a separate runner). */
+  jobs?: {
+    consumerLane?: JobRunIn;
+    queueNamePrefix?: string;
+  };
 };
 
 const DEFAULT_JWT_SECRET = "test-stack-secret-minimum-32-characters!!";
@@ -213,6 +235,26 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
   const events = createEventCollector();
   const registry = createRegistry([...options.features]);
 
+  // Built before buildServer() so it can be merged into dispatcherOptions
+  // (write handlers' `ctx.jobRunner.dispatch(...)` and the afterCommit
+  // event-trigger hook both need it present at dispatcher-construction
+  // time, same as the prod entrypoint's buildJobRunnerWithHook). Uses the
+  // test-stack's own ephemeral redis — no separate `redisUrl` seam needed.
+  let jobRunner: JobRunner | undefined;
+  if (options.jobs && registry.getAllJobs().size > 0) {
+    const redisOpts = testRedis.redis.options;
+    jobRunner = createJobRunner({
+      registry,
+      context: { db: testDb.db, registry },
+      redisUrl: `redis://${redisOpts.host}:${redisOpts.port}/${redisOpts.db}`,
+      ...(options.jobs.consumerLane !== undefined && { consumerLane: options.jobs.consumerLane }),
+      ...(options.jobs.queueNamePrefix !== undefined && {
+        queueNamePrefix: options.jobs.queueNamePrefix,
+      }),
+    });
+    await jobRunner.start();
+  }
+
   // Auto-configure search for tenant 1 based on registry
   if (enabledHooks.includes("search")) {
     const searchableFields: string[] = [];
@@ -285,6 +327,7 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
     dispatcherOptions: {
       idempotency,
       ...(options.effectiveFeatures && { effectiveFeatures: options.effectiveFeatures }),
+      ...(jobRunner && { jobRunner }),
     },
     eventDedup,
     sseBroker,
@@ -354,7 +397,9 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
     dispatcher: server.dispatcher,
     ...(eventDispatcher ? { eventDispatcher } : {}),
     ...(server.lifecycle ? { lifecycle: server.lifecycle } : {}),
+    ...(jobRunner ? { jobRunner } : {}),
     cleanup: async () => {
+      if (jobRunner) await jobRunner.stop();
       if (eventDispatcher) await eventDispatcher.stop();
       await server.observability.shutdown();
       await Promise.all([testDb.cleanup(), testRedis.cleanup()]);

package/src/testing/boot-validator-fixture.ts

@@ -1,3 +1,4 @@
+import { SEARCHABLE_FALSE_WHITELIST } from "../engine/boot-validator/entity-list-screens";
 import type {
   EntityDefinition,
   EntityListScreenDefinition,
@@ -7,8 +8,6 @@ import type {
 import { normalizeListColumn } from "../engine/types/screen";
 import { featureHasI18nSurface, requiredKeysFromFeature } from "../i18n/required-surface-keys";
 
-const SEARCHABLE_FALSE_WHITELIST = new Set(["download-attempt-list"]);
-
 function ensureEntityListSortable(feature: FeatureDefinition): FeatureDefinition {
   if (!feature.entities) return feature;
   const entities: Record<string, EntityDefinition> = { ...feature.entities };

package/src/engine/__tests__/deep-link.test.ts

@@ -1,35 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { buildDeepLinkUrl } from "../deep-link";
-
-describe("buildDeepLinkUrl()", () => {
-  test("screenId only", () => {
-    expect(buildDeepLinkUrl("https://app.example.com", { screenId: "jobs" })).toBe(
-      "https://app.example.com/jobs",
-    );
-  });
-
-  test("screenId + entityId", () => {
-    expect(
-      buildDeepLinkUrl("https://app.example.com", { screenId: "jobs", entityId: "job-1" }),
-    ).toBe("https://app.example.com/jobs/job-1");
-  });
-
-  test("workspaceId + screenId + entityId, in path order", () => {
-    expect(
-      buildDeepLinkUrl("https://app.example.com", {
-        workspaceId: "admin",
-        screenId: "jobs",
-        entityId: "job-1",
-      }),
-    ).toBe("https://app.example.com/admin/jobs/job-1");
-  });
-
-  test("strips trailing slash(es) from baseUrl", () => {
-    expect(buildDeepLinkUrl("https://app.example.com/", { screenId: "jobs" })).toBe(
-      "https://app.example.com/jobs",
-    );
-    expect(buildDeepLinkUrl("https://app.example.com//", { screenId: "jobs" })).toBe(
-      "https://app.example.com/jobs",
-    );
-  });
-});

package/src/engine/deep-link.ts

@@ -1,23 +0,0 @@
-// Deep-Link-URL-Builder für Notification-Templates (#449, Lazy-Scope: nur
-// Notification→Screen, kein Permalink-Sharing-Layer). Server-seitig nutzbar
-// (kein React) — der Renderer hat mit `formatPath`
-// (packages/renderer/src/app/nav.tsx) dasselbe Pfad-Format fürs Client-Routing,
-// hier bewusst dupliziert statt importiert: `renderer` zieht React als
-// Dependency, Notification-Data-Fns laufen server-seitig im Write-Handler.
-//
-// baseUrl kommt vom App-Autor (analog `AuthMailOptions.baseUrl` /
-// magic-link-mail.ts appendToken) — kein Auto-Detect, kein Env-Var-Read hier.
-
-export type DeepLinkTarget = {
-  readonly screenId: string;
-  readonly entityId?: string;
-  readonly workspaceId?: string;
-};
-
-export function buildDeepLinkUrl(baseUrl: string, target: DeepLinkTarget): string {
-  const segments: string[] = [];
-  if (target.workspaceId !== undefined) segments.push(target.workspaceId);
-  segments.push(target.screenId);
-  if (target.entityId !== undefined) segments.push(target.entityId);
-  return `${baseUrl.replace(/\/+$/, "")}/${segments.join("/")}`;
-}