@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/files/local-provider.ts

@@ -1,16 +1,35 @@
 import { createReadStream, createWriteStream } from "node:fs";
 import { mkdir, readFile, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve, sep } from "node:path";
 import { pipeline } from "node:stream/promises";
-import type { FileStorageProvider } from "./types";
+import { assertSafeStorageKey, type FileStorageProvider } from "./types";
 
 // Local-filesystem backend — intended for dev + tests. Production deploys
 // pick an object-store provider (S3/R2/…). mimeType is ignored here; the
 // filesystem tracks no metadata beyond what the caller stores on FileRef.
 export function createLocalProvider(basePath: string): FileStorageProvider {
+  const resolvedBase = resolve(basePath);
+
+  // Callers are expected to only ever pass keys built by buildStorageKey(),
+  // but the storage layer shouldn't rely solely on that — this resolves the
+  // real path and rejects anything that escapes basePath (e.g. a `..`
+  // segment that slipped past an upstream check), regardless of the key's
+  // source.
+  function resolveContainedPath(key: string): string {
+    assertSafeStorageKey(key);
+    // assertSafeStorageKey rejects every literal "."/".." segment, which
+    // covers all string-based traversal a join+resolve can produce; this
+    // startsWith check is a second, independent line of defense in case a
+    // future caller feeds resolveContainedPath something pre-resolved.
+    const filePath = resolve(join(basePath, key));
+    if (filePath !== resolvedBase && !filePath.startsWith(resolvedBase + sep)) {
+      throw new Error(`storage key escapes basePath: "${key}"`);
+    }
+    return filePath;
+  }
   return {
     async write(key: string, data: Uint8Array, _mimeType?: string): Promise<void> {
-      const filePath = join(basePath, key);
+      const filePath = resolveContainedPath(key);
       await mkdir(dirname(filePath), { recursive: true });
       await writeFile(filePath, data);
     },
@@ -26,7 +45,7 @@ export function createLocalProvider(basePath: string): FileStorageProvider {
       // Hygiene; ein periodischer cron-cleanup auf alten `.tmp`-Files
       // ist die saubere Loesung wenn das in Production realistisch
       // greift.
-      const filePath = join(basePath, key);
+      const filePath = resolveContainedPath(key);
       const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
       await mkdir(dirname(filePath), { recursive: true });
       try {
@@ -41,7 +60,7 @@ export function createLocalProvider(basePath: string): FileStorageProvider {
     },
 
     async read(key: string): Promise<Uint8Array> {
-      const filePath = join(basePath, key);
+      const filePath = resolveContainedPath(key);
       return readFile(filePath);
     },
 
@@ -55,7 +74,7 @@ export function createLocalProvider(basePath: string): FileStorageProvider {
       // (z.B. ENOENT bei Missing-File faellt erst beim ersten chunk-
       // pull, nicht beim readStream-Aufruf — gleiches Lazy-Verhalten
       // wie inmemory + S3).
-      const filePath = join(basePath, key);
+      const filePath = resolveContainedPath(key);
       const stream = createReadStream(filePath);
       return {
         async *[Symbol.asyncIterator]() {
@@ -76,13 +95,13 @@ export function createLocalProvider(basePath: string): FileStorageProvider {
     },
 
     async delete(key: string): Promise<void> {
-      const filePath = join(basePath, key);
+      const filePath = resolveContainedPath(key);
       await rm(filePath, { force: true });
     },
 
     async exists(key: string): Promise<boolean> {
       try {
-        await stat(join(basePath, key));
+        await stat(resolveContainedPath(key));
         return true;
       } catch {
         return false;

package/src/files/provider-resolver.ts

@@ -12,11 +12,12 @@
 // file-foundation re-exports `createFileProviderForTenant` + the plugin types
 // (moved here from there) so existing imports keep working.
 
+import type { FileProviderResolver } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
 import type { DbConnection } from "../db/connection";
 import type { TenantDb } from "../db/tenant-db";
 import { EXT_FILE_PROVIDER, FILE_PROVIDER_CONFIG_KEY } from "../engine/extension-names";
 import { SYSTEM_USER_ID } from "../engine/system-user";
-import type { ConfigAccessor, ConfigAccessorFactory, Registry, TenantId } from "../engine/types";
+import type { ConfigAccessor, ConfigAccessorFactory, Registry } from "../engine/types";
 import type { SecretsContext } from "../secrets";
 import type { FileStorageProvider } from "./types";
 
@@ -120,10 +121,7 @@ export async function createFileProviderForTenant(
   return usage.options.build(ctx, tenantId);
 }
 
-// A bound, per-tenant provider resolver. One instance serves all tenants
-// (tenantId is the call argument) — the single spine shared by upload routes,
-// ctx.files and the GDPR jobs.
-export type FileProviderResolver = (tenantId: TenantId) => Promise<FileStorageProvider>;
+export type { FileProviderResolver } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
 
 export type FileProviderResolverDeps = {
   readonly registry?: Registry;
@@ -138,21 +136,34 @@ export type FileProviderResolverDeps = {
 // SYSTEM identity: provider construction is an infra read, distinct from the
 // request user's authorization which stays at the route accessGuard.
 export function makeFileProviderResolver(deps: FileProviderResolverDeps): FileProviderResolver {
-  return async (tenantId) => {
-    if (!deps.registry || !deps._configAccessorFactory || !deps.db) {
-      throw new Error(
-        "makeFileProviderResolver: registry/_configAccessorFactory/db missing — " +
-          "mount the config + file-foundation features and wire context.db",
+  // Per-tenant cache (698/2) — without it, every resolveProvider(tenantId)
+  // call re-reads config + secrets from the DB, even though the provider is
+  // effectively static per tenant for the process lifetime. A rejected
+  // promise is evicted so a transient failure (or a secret genuinely not
+  // configured yet) doesn't permanently poison this tenant's entry.
+  const cache = new Map<string, Promise<FileStorageProvider>>();
+  return (tenantId) => {
+    const cached = cache.get(tenantId);
+    if (cached) return cached;
+    const built = (async () => {
+      if (!deps.registry || !deps._configAccessorFactory || !deps.db) {
+        throw new Error(
+          "makeFileProviderResolver: registry/_configAccessorFactory/db missing — " +
+            "mount the config + file-foundation features and wire context.db",
+        );
+      }
+      const config = deps._configAccessorFactory({
+        user: { id: SYSTEM_USER_ID, tenantId },
+        db: deps.db,
+        secrets: deps.secrets,
+      });
+      return createFileProviderForTenant(
+        { config, registry: deps.registry, secrets: deps.secrets, _userId: SYSTEM_USER_ID },
+        tenantId,
       );
-    }
-    const config = deps._configAccessorFactory({
-      user: { id: SYSTEM_USER_ID, tenantId },
-      db: deps.db,
-      secrets: deps.secrets,
-    });
-    return createFileProviderForTenant(
-      { config, registry: deps.registry, secrets: deps.secrets, _userId: SYSTEM_USER_ID },
-      tenantId,
-    );
+    })();
+    built.catch(() => cache.delete(tenantId));
+    cache.set(tenantId, built);
+    return built;
   };
 }

package/src/files/types.ts

@@ -6,60 +6,11 @@ export type FileMetadata = {
   readonly size: number;
 };
 
-// Options for `getSignedUrl`. `contentDisposition` lets the caller hint the
-// browser to download-with-name vs inline-display (maps to ResponseContent-
-// Disposition on S3). Keep the option-bag small and additive; provider impls
-// that don't support a given hint should ignore it rather than error.
-export type SignedUrlOptions = {
-  readonly contentDisposition?: string;
-};
-
-// Options fuer `writeStream`. `mimeType` ist Content-Type-Hint analog zu
-// `write`. `contentLength` ist optional fuer Provider die einen Length-
-// Header brauchen (S3 multipart hat einen TransferManager, kann auch ohne
-// length); local-Provider ignoriert beides.
-export type WriteStreamOptions = {
-  readonly mimeType?: string;
-  readonly contentLength?: number;
-};
-
-// Primitive storage contract: key+bytes in, bytes out. Metadata (fileName,
-// mimeType, size) lives on the FileRef row — the provider only needs to
-// shuttle bytes. `mimeType` on write() is a hint for providers that need a
-// Content-Type header (S3/R2/…); local filesystems can ignore it.
-//
-// **Streaming (`writeStream` + `readStream`) ist PFLICHT** — beide
-// Methoden sind required, kein optional-feature. Begruendung:
-//   - User-Data-Export (Atom 3c) braucht beide, sonst silent fail bei
-//     erstem Job mit fileRefs in Production.
-//   - Apps die nur kleine Files (Avatar-Uploads, Profile-Pics) handeln,
-//     koennen trivial via `oneShot`-Pattern den Stream-Contract erfuellen
-//     (single-chunk yield von write/read-Bytes). 5 Zeilen pro Provider.
-//   - Optional-Type wuerde TypeScript-Lying erlauben: Type sagt "kann
-//     fehlen", Worker throws zur Runtime → App-Authors sehen den Bug
-//     erst in Production. Required + TS-enforced ist ehrlich.
-//
-// `getSignedUrl` BLEIBT optional: object-store backends (S3/R2/GCS)
-// implement it so clients can download directly from the provider after
-// the server has checked access — offloads bandwidth and enables browser-
-// native caching. Filesystem providers leave it undefined; the route then
-// returns 501 and the client falls back to streaming via GET /files/:id.
-// Callers must feature-detect via `typeof provider.getSignedUrl === "function"`.
-// Hier ist Optional korrekt weil die Fallback-Pfad existiert — kein
-// silent-fail, sondern 501 + alternativer download.
-export type FileStorageProvider = {
-  write(key: string, data: Uint8Array, mimeType?: string): Promise<void>;
-  writeStream(
-    key: string,
-    source: AsyncIterable<Uint8Array>,
-    options?: WriteStreamOptions,
-  ): Promise<void>;
-  read(key: string): Promise<Uint8Array>;
-  readStream(key: string): AsyncIterable<Uint8Array>;
-  delete(key: string): Promise<void>;
-  exists(key: string): Promise<boolean>;
-  getSignedUrl?(key: string, expiresInSeconds: number, options?: SignedUrlOptions): Promise<string>;
-};
+export type {
+  FileStorageProvider,
+  SignedUrlOptions,
+  WriteStreamOptions,
+} from "@cosmicdrift/kumiko-types/file-storage-provider-types";
 
 export type FileValidationOptions = {
   readonly maxSize?: string | undefined;
@@ -133,6 +84,12 @@ export function validateFile(
   return null;
 }
 
+export function assertSafeStorageKey(key: string): void {
+  if (key.split("/").some((segment) => segment === "." || segment === "..")) {
+    throw new Error(`storage key contains a path-traversal segment: "${key}"`);
+  }
+}
+
 export function buildStorageKey(
   tenantId: TenantId,
   entityType: string,
@@ -141,6 +98,7 @@ export function buildStorageKey(
   fileName: string,
   uniqueId: string,
 ): string {
-  const ext = fileName.split(".").pop() ?? "bin";
+  const rawExt = fileName.split(".").pop() ?? "";
+  const ext = /^[A-Za-z0-9]+$/.test(rawExt) ? rawExt.toLowerCase() : "bin";
   return `${tenantId}/${entityType}/${entityId}/${fieldName}/${uniqueId}.${ext}`;
 }

package/src/i18n/__tests__/required-surface-keys.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, test } from "bun:test";
+import { booleanFacetOptionKeys, selectFacetOptionKey } from "../required-surface-keys";
+
+describe("required-surface-keys helpers", () => {
+  test("booleanFacetOptionKeys emits true/false option keys", () => {
+    expect(booleanFacetOptionKeys("tenant", "tenant", "isEnabled")).toEqual([
+      "tenant:entity:tenant:field:isEnabled:option:true",
+      "tenant:entity:tenant:field:isEnabled:option:false",
+    ]);
+  });
+
+  test("selectFacetOptionKey encodes option value", () => {
+    expect(selectFacetOptionKey("user", "user", "status", "active")).toBe(
+      "user:entity:user:field:status:option:active",
+    );
+  });
+});

package/src/i18n/required-surface-keys.ts

@@ -1,16 +1,21 @@
+import { isExtensionEditSection, normalizeListColumn } from "../engine/screen-helpers";
 import type {
   ActionFormScreenDefinition,
   ConfigEditScreenDefinition,
+  DashboardFilterDefinition,
+  DashboardPanelDefinition,
+  DashboardScreenDefinition,
   EntityEditScreenDefinition,
   EntityListScreenDefinition,
   FeatureDefinition,
   NavDefinition,
+  ProjectionDetailScreenDefinition,
+  ProjectionListScreenDefinition,
   RowAction,
   ScreenDefinition,
   ToolbarAction,
   WorkspaceDefinition,
 } from "../engine/types";
-import { isExtensionEditSection, normalizeListColumn } from "../engine/types/screen";
 
 /** Pseudo-entity for actionForm field labels (renderer action-form-shim). */
 export const ACTION_FORM_ENTITY = "__action-form__";
@@ -18,10 +23,31 @@ export const ACTION_FORM_ENTITY = "__action-form__";
 /** Pseudo-entity for configEdit field labels (renderer config-edit-shim). */
 export const CONFIG_EDIT_ENTITY = "__config-edit__";
 
+/** Pseudo-entity for projectionDetail field labels (renderer projection-detail-shim). */
+export const PROJECTION_DETAIL_ENTITY = "__projection-detail__";
+
 export function fieldLabelKey(featureName: string, entityName: string, fieldName: string): string {
   return `${featureName}:entity:${entityName}:field:${fieldName}`;
 }
 
+export function booleanFacetOptionKeys(
+  featureName: string,
+  entityName: string,
+  fieldName: string,
+): readonly string[] {
+  const base = `${featureName}:entity:${entityName}:field:${fieldName}:option`;
+  return [`${base}:true`, `${base}:false`];
+}
+
+export function selectFacetOptionKey(
+  featureName: string,
+  entityName: string,
+  fieldName: string,
+  value: string,
+): string {
+  return `${featureName}:entity:${entityName}:field:${fieldName}:option:${value}`;
+}
+
 export function screenTitleKey(screenId: string): string {
   return `screen:${screenId}.title`;
 }
@@ -46,6 +72,34 @@ function pushRowActionKeys(out: Set<string>, action: RowAction): void {
   }
 }
 
+function pushDashboardScreenKeys(out: Set<string>, dashboard: DashboardScreenDefinition): void {
+  for (const panel of dashboard.panels) pushDashboardPanelKeys(out, panel);
+  if (dashboard.filter !== undefined) pushDashboardFilterKeys(out, dashboard.filter);
+}
+
+function pushDashboardPanelKeys(out: Set<string>, panel: DashboardPanelDefinition): void {
+  // skip: custom-Panel übersetzt sich selbst, kein Key hier
+  if (panel.kind === "custom") return;
+  pushKey(out, panel.label);
+  if (panel.kind === "stat-group") {
+    for (const stat of panel.stats) pushKey(out, stat.label);
+  }
+  if (panel.kind === "list") {
+    for (const col of panel.columns) {
+      const normalized = normalizeListColumn(col);
+      if (normalized.label !== undefined) pushKey(out, normalized.label);
+    }
+  }
+  if (panel.kind === "feed" && panel.emptyLabel !== undefined) pushKey(out, panel.emptyLabel);
+}
+
+function pushDashboardFilterKeys(out: Set<string>, filter: DashboardFilterDefinition): void {
+  pushKey(out, filter.label);
+  if (filter.allLabel !== undefined) pushKey(out, filter.allLabel);
+  if (filter.placeholder !== undefined) pushKey(out, filter.placeholder);
+  for (const opt of filter.options ?? []) pushKey(out, opt.label);
+}
+
 function pushToolbarActionKeys(out: Set<string>, action: ToolbarAction): void {
   pushKey(out, action.label);
   if (action.kind === "writeHandler") {
@@ -76,6 +130,21 @@ export function requiredKeysFromScreen(
       for (const action of list.toolbarActions ?? []) pushToolbarActionKeys(out, action);
       break;
     }
+    case "projectionList": {
+      const list = screen as ProjectionListScreenDefinition;
+      // Keine Entity → keine field-label-Fallbacks; nur explizite Column-Labels.
+      for (const col of list.columns) {
+        const normalized = normalizeListColumn(col);
+        if (normalized.label !== undefined) pushKey(out, normalized.label);
+      }
+      for (const action of list.rowActions ?? []) pushRowActionKeys(out, action);
+      for (const action of list.toolbarActions ?? []) pushToolbarActionKeys(out, action);
+      break;
+    }
+    case "dashboard": {
+      pushDashboardScreenKeys(out, screen as DashboardScreenDefinition);
+      break;
+    }
     case "entityEdit": {
       const edit = screen as EntityEditScreenDefinition;
       pushKey(out, edit.submitLabel);
@@ -136,6 +205,20 @@ export function requiredKeysFromScreen(
       }
       break;
     }
+    case "projectionDetail": {
+      const detail = screen as ProjectionDetailScreenDefinition;
+      for (const section of detail.layout.sections) {
+        if (isExtensionEditSection(section)) continue; // rejected at boot, unreachable here
+        pushKey(out, section.title);
+        for (const f of section.fields) {
+          const fieldName = editFieldName(f);
+          const override = detail.fieldLabels?.[fieldName];
+          if (override !== undefined) pushKey(out, override);
+          else out.add(fieldLabelKey(featureName, PROJECTION_DETAIL_ENTITY, fieldName));
+        }
+      }
+      break;
+    }
     case "custom":
       break;
   }
@@ -155,6 +238,41 @@ export function requiredKeysFromWorkspace(ws: WorkspaceDefinition): readonly str
   return [...out];
 }
 
+function collectEntityListFilterKeys(feature: FeatureDefinition, out: Set<string>): void {
+  for (const screen of Object.values(feature.screens)) {
+    if (screen.type !== "entityList") continue;
+    const entity = feature.entities?.[screen.entity];
+    if (!entity) continue;
+    for (const [fieldName, rawDef] of Object.entries(entity.fields)) {
+      const def = rawDef as {
+        readonly filterable?: boolean;
+        readonly type?: string;
+        readonly options?: readonly string[];
+      };
+      if (def.filterable !== true) continue;
+      if (def.type === "boolean") {
+        for (const key of booleanFacetOptionKeys(feature.name, screen.entity, fieldName)) {
+          out.add(key);
+        }
+      } else if (def.type === "select" && Array.isArray(def.options)) {
+        for (const value of def.options) {
+          out.add(selectFacetOptionKey(feature.name, screen.entity, fieldName, value));
+        }
+      }
+    }
+  }
+}
+
+export function featureHasI18nSurface(feature: FeatureDefinition): boolean {
+  if (Object.keys(feature.screens).length > 0) return true;
+  if (Object.keys(feature.navs).length > 0) return true;
+  if (Object.keys(feature.workspaces).length > 0) return true;
+  for (const def of Object.values(feature.configKeys)) {
+    if (def.mask !== undefined) return true;
+  }
+  return false;
+}
+
 export function requiredKeysFromFeature(feature: FeatureDefinition): readonly string[] {
   const out = new Set<string>();
 
@@ -170,6 +288,7 @@ export function requiredKeysFromFeature(feature: FeatureDefinition): readonly st
   for (const def of Object.values(feature.configKeys)) {
     pushKey(out, def.mask?.title);
   }
+  collectEntityListFilterKeys(feature, out);
 
   return [...out];
 }

package/src/jobs/__tests__/job-queue-depth.integration.test.ts

@@ -0,0 +1,82 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createRegistry, defineFeature } from "../../engine";
+import type { AppContext, Registry } from "../../engine/types";
+import { createPrometheusMeter, registerStandardMetrics } from "../../observability";
+import { createTestRedis, type TestRedis } from "../../stack";
+import { sleep } from "../../testing";
+import { createJobRunner } from "../job-runner";
+
+let testRedis: TestRedis;
+let redisUrl: string;
+
+const testFeature = defineFeature("test-queue-depth", (r) => {
+  r.job("noop", { trigger: { manual: true } }, async () => {});
+});
+
+beforeAll(async () => {
+  testRedis = await createTestRedis();
+  redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
+});
+
+afterAll(async () => {
+  await testRedis.cleanup();
+});
+
+describe("job-runner — kumiko_job_queue_depth", () => {
+  test("start() polls BullMQ counts into the gauge, stop() tears the poller down", async () => {
+    const registry: Registry = createRegistry([testFeature]);
+    const meter = createPrometheusMeter();
+    registerStandardMetrics(meter);
+    const context: AppContext = { meter };
+    const queueNamePrefix = `kumiko-test-qd-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+    const runner = createJobRunner({
+      registry,
+      context,
+      redisUrl,
+      consumerLane: "worker",
+      queueNamePrefix,
+    });
+
+    try {
+      await runner.start();
+
+      const snapshot = meter.snapshot().get("kumiko_job_queue_depth");
+      expect(snapshot).toBeDefined();
+      const waitingSlot = snapshot?.slots.find(
+        (s) => s.labels?.["lane"] === "worker" && s.labels?.["state"] === "waiting",
+      );
+      expect(waitingSlot).toBeDefined();
+      expect((waitingSlot as { value: number }).value).toBe(0);
+      // BullMQ's fresh Worker connection is still settling right after
+      // start() returns (no boot/cron job here to have already warmed it
+      // up, unlike every other scenario in this suite) — stop() immediately
+      // after start() races the Worker's own connection teardown and throws
+      // an unrelated "Connection is closed" from ioredis. Production runners
+      // live far longer than this; the race is a test-only artifact of
+      // start()+stop() with zero work in between.
+      await sleep(50);
+    } finally {
+      await runner.stop();
+      const keys = await testRedis.redis.keys(`bull:${queueNamePrefix}-worker:*`);
+      if (keys.length > 0) await testRedis.redis.del(...keys);
+    }
+  });
+
+  test("enqueuer-only runner (no consumerLane) never polls — no gauge slots", async () => {
+    const registry: Registry = createRegistry([testFeature]);
+    const meter = createPrometheusMeter();
+    registerStandardMetrics(meter);
+    const context: AppContext = { meter };
+    const queueNamePrefix = `kumiko-test-qd-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+    const runner = createJobRunner({ registry, context, redisUrl, queueNamePrefix });
+    try {
+      await runner.start();
+      const snapshot = meter.snapshot().get("kumiko_job_queue_depth");
+      expect(snapshot?.slots.length ?? 0).toBe(0);
+    } finally {
+      await runner.stop();
+    }
+  });
+});