@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/foundation-shared/config-helpers.ts

@@ -0,0 +1,67 @@
+// Shared config-read helpers used by the per-tenant Foundation factories
+// (ai-foundation, mail-foundation, file-foundation). Each foundation reads
+// its config-keys + secret out of `ctx`, narrows undefined → throw, and
+// dispatches to a provider. The narrowing helpers live here as a single
+// source so all three foundations report errors the same way and a fix
+// to one error-message format reaches all callers.
+//
+// **Why a shared module instead of duplicate copies:**
+//   First two foundations (ai + mail) hand-rolled identical helpers,
+//   the third (file) made it three times. That's the threshold where
+//   premature-abstraction-warnings flip to DRY-warnings — three nearly-
+//   identical 25-LOC helper-pairs across three files would diverge in
+//   error-text under maintenance, exactly the bug-class extraction
+//   prevents.
+//
+// **What this module is NOT:**
+//   - Not a feature — no `defineFeature`, no boot-time registration.
+//   - Not a barrel for everything — only the helpers actually shared
+//     across foundations live here. Per-foundation transport/provider-
+//     factories stay in their own package.
+
+/**
+ * Narrow `value | undefined` → `value` with a clear message that names
+ * which config key resolved to nothing. Use for keys whose `undefined`
+ * means a registry misconfiguration (no value + no default).
+ *
+ * Foundation-Pattern: this is the wrap-helper around `await ctx.config(
+ * featureFoundationFeature.exports.configKeys.someKey)` — the call-site
+ * stays a single line per key.
+ *
+ * **`featureName` is the qualified-name prefix in the error** (e.g.
+ * `"ai-foundation"`, `"mail-foundation"`) — included so that an exception
+ * surfaced from a multi-foundation app pinpoints the failing foundation.
+ */
+export function requireDefined<T>(value: T | undefined, featureName: string, label: string): T {
+  if (value === undefined) {
+    throw new Error(
+      `${featureName}: '${label}' config key resolved to undefined — registry misconfigured (no value + no default)`,
+    );
+  }
+  return value;
+}
+
+/**
+ * Narrow `string | undefined` → non-empty `string`. Tighter than
+ * `requireDefined` for the case where the registry HAS a default (often
+ * `""`) but the foundation requires the tenant to have set a real value
+ * before the factory can build a working transport / provider.
+ *
+ * Typical use: SMTP host, S3 bucket, model id — values without which the
+ * downstream SDK would 400 with a cryptic message. The clearer "tenant
+ * must configure X via tenant-admin UI" lands at the call-site instead.
+ */
+export function requireNonEmpty(
+  value: string | undefined,
+  featureName: string,
+  label: string,
+  uiHint = "Set via tenant-admin UI or seed-handler.",
+): string {
+  const defined = requireDefined(value, featureName, label);
+  if (defined.length === 0) {
+    throw new Error(
+      `${featureName}: '${label}' is empty — tenant must configure it before use. ${uiHint}`,
+    );
+  }
+  return defined;
+}

package/src/foundation-shared/index.ts

@@ -0,0 +1,4 @@
+// Public API of foundation-shared — utilities consumed by the per-tenant
+// Foundation packages (ai-foundation, mail-foundation, file-foundation).
+
+export { requireDefined, requireNonEmpty } from "./config-helpers";

package/src/jobs/__tests__/job-system-user.integration.ts

@@ -0,0 +1,194 @@
+import { randomBytes } from "node:crypto";
+import {
+  createEncryptionProvider,
+  createTenantDb,
+  type DbConnection,
+} from "@cosmicdrift/kumiko-framework/db";
+import {
+  access,
+  createRegistry,
+  createTenantConfig,
+  defineFeature,
+  type Registry,
+  type SessionUser,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createArchivedStreamsTable,
+  createEventsTable,
+} from "@cosmicdrift/kumiko-framework/event-store";
+import { createJobRunner, type JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
+import {
+  createTestDb,
+  createTestRedis,
+  pushTables,
+  type TestDb,
+  type TestRedis,
+  TestUsers,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { bridgeStub, sleep } from "@cosmicdrift/kumiko-framework/testing";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { ConfigHandlers } from "../../config/constants";
+import { createConfigAccessor, createConfigFeature } from "../../config/feature";
+import { type ConfigResolver, createConfigResolver } from "../../config/resolver";
+import { configValuesTable } from "../../config/table";
+
+// --- Setup ---
+
+let testDb: TestDb;
+let testRedis: TestRedis;
+let db: DbConnection;
+let registry: Registry;
+let resolver: ConfigResolver;
+let jobRunner: JobRunner;
+
+const testEncryptionKey = randomBytes(32).toString("base64");
+
+// Feature with a system-only config key and a job that sets it
+const billingFeature = defineFeature("billing", (r) => {
+  r.requires("config");
+
+  r.config({
+    keys: {
+      monthlyTotal: createTenantConfig("number", {
+        default: 0,
+        write: access.system,
+        read: access.roles("Admin"),
+      }),
+    },
+  });
+
+  // Job that calculates monthly total and writes it via SYSTEM_USER.
+  // Post-ES the write path is the config:write:set handler — the old
+  // resolver.set escape hatch is gone. checkWriteAccess grants a
+  // SYSTEM_ROLE caller the right to write system-only keys that Admin
+  // cannot touch, so the security invariant (see Admin test below) holds.
+  r.job("calculateTotal", { trigger: { manual: true } }, async (_payload, ctx) => {
+    const systemUser = ctx["systemUser"] as SessionUser;
+    const jobDb = ctx["db"] as DbConnection;
+    const reg = ctx["registry"] as Registry;
+
+    ctx.log?.info("Calculating monthly total...");
+    const total = 42000;
+
+    const handler = reg.getWriteHandler("config:write:set");
+    if (handler) {
+      const parsed = handler.schema.parse({
+        key: "billing:config:monthly-total",
+        value: total,
+      });
+      const tenantDb = createTenantDb(jobDb, systemUser.tenantId, "system");
+      await handler.handler(
+        { type: "config:write:set", payload: parsed, user: systemUser },
+        {
+          db: tenantDb,
+          registry: reg,
+          configResolver: ctx["configResolver"] as ConfigResolver,
+          ...bridgeStub(),
+        },
+      );
+    }
+
+    ctx.log?.info(`Set monthlyTotal to ${total}`);
+  });
+});
+
+const configFeature = createConfigFeature();
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  testRedis = await createTestRedis();
+  db = testDb.db;
+
+  await pushTables(db, { configValuesTable });
+  // Post-ES config writes go through the event-store executor, which needs
+  // the framework events + archived-streams tables to exist before the
+  // first append. setupTestStack provisions them automatically; this test
+  // builds its DB manually (createTestDb + pushTables), so we do it here.
+  await createEventsTable(db);
+  await createArchivedStreamsTable(db);
+
+  const encryption = createEncryptionProvider(testEncryptionKey);
+  resolver = createConfigResolver({ encryption });
+
+  registry = createRegistry([configFeature, billingFeature]);
+
+  const redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
+
+  jobRunner = createJobRunner({
+    registry,
+    context: { db, registry, configResolver: resolver, configEncryption: encryption },
+    redisUrl,
+    consumerLane: "worker",
+    queueNamePrefix: `kumiko-system-user-test-${Date.now()}`,
+  });
+
+  await jobRunner.start();
+});
+
+afterAll(async () => {
+  await jobRunner.stop();
+  await testDb.cleanup();
+  await testRedis.cleanup();
+});
+
+// --- Tests ---
+
+describe("SYSTEM_USER in jobs", () => {
+  test("job sets system-only config via ctx.systemUser", async () => {
+    // Dispatch with tenantId in payload so systemUser gets the right tenant
+    await jobRunner.dispatch("billing:job:calculate-total", {
+      tenantId: "00000000-0000-4000-8000-000000000001",
+    });
+    await sleep(1500);
+
+    // Config should have been set by the job via SYSTEM_USER
+    const configFn = createConfigAccessor(
+      registry,
+      resolver,
+      "00000000-0000-4000-8000-000000000001",
+      "11111111-0000-4000-8000-000000000099",
+      db,
+    );
+    const total = await configFn("billing:config:monthly-total");
+    expect(total).toBe(42000);
+    expect(typeof total).toBe("number");
+  });
+
+  test("Admin cannot set system-only config directly", async () => {
+    const handler = registry.getWriteHandler(ConfigHandlers.set);
+    if (!handler) throw new Error("config.set not found");
+
+    const parsed = handler.schema.parse({
+      key: "billing:config:monthly-total",
+      value: 99999,
+    });
+
+    const adminUser = TestUsers.admin;
+    const result = await handler.handler(
+      { type: ConfigHandlers.set, payload: parsed, user: adminUser },
+      {
+        db: createTenantDb(db, adminUser.tenantId, "system"),
+        registry,
+        configResolver: resolver,
+        ...bridgeStub(),
+      },
+    );
+
+    expect(result.isSuccess).toBe(false);
+    if (!result.isSuccess) {
+      expect(result.error.code).toBe("access_denied");
+      expect(result.error.details).toMatchObject({ reason: "config_key_is_system_only" });
+    }
+  });
+
+  test("value set by job is still 42000, not overwritten by Admin attempt", async () => {
+    const configFn = createConfigAccessor(
+      registry,
+      resolver,
+      "00000000-0000-4000-8000-000000000001",
+      "11111111-0000-4000-8000-000000000001",
+      db,
+    );
+    expect(await configFn("billing:config:monthly-total")).toBe(42000);
+  });
+});

package/src/jobs/__tests__/jobs-events.integration.ts

@@ -0,0 +1,143 @@
+// Event-shape contract for jobRun aggregate. Pins the three domain
+// events (run-started / run-completed / run-failed) against their
+// registered schemas + the stable type-name constants. A silent rename
+// (event-type-string, aggregateType, or payload-shape) fails here
+// instead of breaking MSP consumers and audit exports.
+//
+// The jobs integration test (jobs-feature.integration.ts) covers the
+// projection side (list + detail queries). This file covers the event
+// side — complementary coverage, minimal overlap.
+
+import { createRegistry, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable, eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestDb,
+  createTestRedis,
+  pushTables,
+  type TestDb,
+  type TestRedis,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { eq } from "drizzle-orm";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { runCompletedSchema, runFailedSchema, runStartedSchema } from "../events";
+import { createJobsFeature } from "../feature";
+import {
+  createJobRunLogger,
+  JOB_RUN_COMPLETED_EVENT,
+  JOB_RUN_FAILED_EVENT,
+  JOB_RUN_STARTED_EVENT,
+} from "../job-run-logger";
+import { jobRunLogsTable, jobRunsTable } from "../job-run-table";
+
+let testDb: TestDb;
+let testRedis: TestRedis;
+let logger: ReturnType<typeof createJobRunLogger>;
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  testRedis = await createTestRedis();
+  const registry = createRegistry([createJobsFeature()]);
+  await pushTables(testDb.db, { jobRunsTable, jobRunLogsTable });
+  await createEventsTable(testDb.db);
+  logger = createJobRunLogger({ db: testDb.db, registry });
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+  await testRedis.cleanup();
+});
+
+beforeEach(async () => {
+  await testDb.db.delete(eventsTable);
+  await testDb.db.delete(jobRunsTable);
+  await testDb.db.delete(jobRunLogsTable);
+});
+
+describe("jobRun event shapes", () => {
+  test("event-type constants are stable strings", () => {
+    // Guard against silent rename. Tests that subscribe via string-match
+    // (MSPs written in userland, audit export tools) break without this.
+    expect(JOB_RUN_STARTED_EVENT).toBe("jobs:event:run-started");
+    expect(JOB_RUN_COMPLETED_EVENT).toBe("jobs:event:run-completed");
+    expect(JOB_RUN_FAILED_EVENT).toBe("jobs:event:run-failed");
+  });
+
+  test("onJobStart writes a run-started event on the jobRun aggregate", async () => {
+    await logger.onJobStart?.("example:job:import", "bull-42", {
+      triggeredById: "u-99",
+      payload: JSON.stringify({ foo: 1 }),
+      attempt: 1,
+    });
+
+    const events = await testDb.db
+      .select()
+      .from(eventsTable)
+      .where(eq(eventsTable.type, JOB_RUN_STARTED_EVENT));
+
+    expect(events.length).toBe(1);
+    const e = events[0];
+    expect(e?.aggregateType).toBe("jobRun");
+    expect(e?.tenantId).toBe(SYSTEM_TENANT_ID);
+    // Payload round-trips through the registered schema — drift would
+    // fail parse here, not silently land on the stream.
+    expect(() => runStartedSchema.parse(e?.payload)).not.toThrow();
+    const p = runStartedSchema.parse(e?.payload);
+    expect(p.jobName).toBe("example:job:import");
+    expect(p.bullJobId).toBe("bull-42");
+    expect(p.triggeredById).toBe("u-99");
+    expect(p.attempt).toBe(1);
+  });
+
+  test("onJobComplete writes a run-completed event with batched logs", async () => {
+    await logger.onJobStart?.("example:job:export", "bull-1", {});
+    await logger.onJobComplete?.("example:job:export", "bull-1", 123, [
+      { level: "info", message: "started", timestamp: Temporal.Now.instant() },
+      { level: "info", message: "done", timestamp: Temporal.Now.instant() },
+    ]);
+
+    const events = await testDb.db
+      .select()
+      .from(eventsTable)
+      .where(eq(eventsTable.type, JOB_RUN_COMPLETED_EVENT));
+
+    expect(events.length).toBe(1);
+    const p = runCompletedSchema.parse(events[0]?.payload);
+    expect(p.duration).toBe(123);
+    expect(p.logs).toHaveLength(2);
+    expect(p.logs[0]?.level).toBe("info");
+  });
+
+  test("onJobFailed writes a run-failed event with error + logs", async () => {
+    await logger.onJobStart?.("example:job:fragile", "bull-9", {});
+    await logger.onJobFailed?.("example:job:fragile", "bull-9", "boom", [
+      { level: "error", message: "kaboom", timestamp: Temporal.Now.instant() },
+    ]);
+
+    const events = await testDb.db
+      .select()
+      .from(eventsTable)
+      .where(eq(eventsTable.type, JOB_RUN_FAILED_EVENT));
+
+    expect(events.length).toBe(1);
+    const p = runFailedSchema.parse(events[0]?.payload);
+    expect(p.error).toBe("boom");
+    expect(p.logs).toHaveLength(1);
+  });
+
+  test("start + complete both land on the SAME aggregate stream", async () => {
+    await logger.onJobStart?.("example:job:stream", "bull-99", {});
+    await logger.onJobComplete?.("example:job:stream", "bull-99", 10, []);
+
+    // Both events should share the same aggregateId — that's what makes
+    // the jobRun a single stream and lets ctx.loadAggregate() reduce
+    // them into a coherent state.
+    const events = await testDb.db
+      .select()
+      .from(eventsTable)
+      .where(eq(eventsTable.aggregateType, "jobRun"));
+
+    expect(events.length).toBe(2);
+    const ids = new Set(events.map((e) => e.aggregateId));
+    expect(ids.size).toBe(1);
+  });
+});