@cosmicdrift/kumiko-framework 0.27.0 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/src/api/server.ts

@@ -23,7 +23,7 @@ import {
   wrapRedisClient,
 } from "../observability";
 import type { DispatcherOptions } from "../pipeline/dispatcher";
-import { createDispatcher } from "../pipeline/dispatcher";
+import { createDispatcher, type Dispatcher } from "../pipeline/dispatcher";
 import { SHARED_INSTANCE_SENTINEL } from "../pipeline/event-consumer-state";
 import type { EventDedup } from "../pipeline/event-dedup";
 import type { EventConsumer, EventDispatcher } from "../pipeline/event-dispatcher";
@@ -195,6 +195,11 @@ export type KumikoServer = {
   jwt: JwtHelper;
   sseBroker: SseBroker;
   observability: ObservabilityProvider;
+  // The command-dispatcher behind /api/* — same idempotency/jobRunner/
+  // lifecycle wiring as HTTP-dispatched writes. For dispatching outside
+  // the HTTP pipeline, e.g. provider-webhook routes that authenticate
+  // via signature instead of JWT (subscription-stripe et al.).
+  dispatcher: Dispatcher;
   // Present when at least one consumer is wired and context.db is a
   // DbConnection. Caller owns the lifecycle: `.start()` in boot, `.stop()`
   // in shutdown. Tests drain via `.runOnce()` instead.
@@ -619,6 +624,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
     jwt,
     sseBroker,
     observability,
+    dispatcher,
     ...(eventDispatcher ? { eventDispatcher } : {}),
     ...(options.lifecycle ? { lifecycle: options.lifecycle } : {}),
   };

package/src/engine/__tests__/engine.test.ts

@@ -23,6 +23,35 @@ describe("defineFeature", () => {
     expect(feature.name).toBe("test");
   });
 
+  test("r.describe() flows into the definition, trimmed", () => {
+    const feature = defineFeature("test", (r) => {
+      r.describe("  Stores per-tenant widgets.  ");
+    });
+    expect(feature.description).toBe("Stores per-tenant widgets.");
+  });
+
+  test("description is absent when r.describe() is not called", () => {
+    const feature = defineFeature("test", () => {});
+    expect("description" in feature).toBe(false);
+  });
+
+  test("r.describe() throws when called twice", () => {
+    expect(() =>
+      defineFeature("test", (r) => {
+        r.describe("first");
+        r.describe("second");
+      }),
+    ).toThrow(/r\.describe\(\) called twice/);
+  });
+
+  test("r.describe() throws on empty or whitespace-only text", () => {
+    expect(() =>
+      defineFeature("test", (r) => {
+        r.describe("   ");
+      }),
+    ).toThrow(/non-empty string/);
+  });
+
   test("collects entities", () => {
     const feature = defineFeature("test", (r) => {
       r.entity(

package/src/engine/define-feature.ts

@@ -153,6 +153,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
 
   let isSystemScoped = false;
   let toggleableDefault: boolean | undefined;
+  let description: string | undefined;
   // Visual-Tree-Slots — at-most-one per feature, only-once-guard im
   // registrar (siehe r.treeActions / r.tree). Undefined wenn das Feature
   // keinen Visual-Tree-Beitrag liefert (Zero-Whitelist-Filter).
@@ -182,6 +183,18 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       isSystemScoped = true;
     },
 
+    describe(text: string): void {
+      if (description !== undefined) {
+        throw new Error(
+          `[Feature ${name}] r.describe() called twice — a feature's description is declared once`,
+        );
+      }
+      if (typeof text !== "string" || text.trim().length === 0) {
+        throw new Error(`[Feature ${name}] r.describe(): text must be a non-empty string`);
+      }
+      description = text.trim();
+    },
+
     requires: (() => {
       const fn = (...featureNames: string[]) => {
         requires.push(...featureNames);
@@ -888,6 +901,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
 
   return {
     name,
+    ...(description !== undefined && { description }),
     systemScope: isSystemScoped,
     exports,
     requires,

package/src/engine/feature-ast/extractors/index.ts

@@ -1,4 +1,5 @@
 export {
+  extractDescribe,
   extractOptionalRequires,
   extractReadsConfig,
   extractRequires,

package/src/engine/feature-ast/extractors/round1.ts

@@ -1,5 +1,6 @@
 import type { CallExpression, SourceFile } from "ts-morph";
 import type {
+  DescribePattern,
   OptionalRequiresPattern,
   ReadsConfigPattern,
   RequiresPattern,
@@ -12,6 +13,7 @@ import {
   fail,
   ok,
   readBooleanProperty,
+  readStringLiteralArgs,
   readVarargsOrArrayProp,
 } from "./shared";
 
@@ -82,6 +84,26 @@ export function extractSystemScope(
   });
 }
 
+export function extractDescribe(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<DescribePattern> {
+  const args = readStringLiteralArgs(call);
+  const text = args?.[0];
+  if (text === undefined || args?.length !== 1) {
+    return fail(
+      "describe",
+      sourceLocationFromNode(call, sourceFile),
+      "expected a single string literal",
+    );
+  }
+  return ok({
+    kind: "describe",
+    source: sourceLocationFromNode(call, sourceFile),
+    text,
+  });
+}
+
 export function extractToggleable(
   call: CallExpression,
   sourceFile: SourceFile,

package/src/engine/feature-ast/parse.ts

@@ -30,6 +30,7 @@ import {
   extractClaimKey,
   extractConfig,
   extractDefineEvent,
+  extractDescribe,
   extractEntity,
   extractEntityHook,
   extractEnvSchema,
@@ -297,6 +298,8 @@ function dispatchExtractor(
       return extractSystemScope(call, sourceFile);
     case "toggleable":
       return extractToggleable(call, sourceFile);
+    case "describe":
+      return extractDescribe(call, sourceFile);
     // Round 2 — object-literal-based static patterns
     case "entity":
       return extractEntity(call, sourceFile);

package/src/engine/feature-ast/patch.ts

@@ -79,6 +79,7 @@ export type PatternId =
   | { readonly kind: "readsConfig" }
   | { readonly kind: "systemScope" }
   | { readonly kind: "toggleable" }
+  | { readonly kind: "describe" }
   | { readonly kind: "config" }
   | { readonly kind: "translations" }
   | { readonly kind: "authClaims" }
@@ -270,6 +271,7 @@ export const SINGLETON_KINDS: ReadonlySet<PatternId["kind"]> = new Set([
   "readsConfig",
   "systemScope",
   "toggleable",
+  "describe",
   "config",
   "translations",
   "authClaims",
@@ -326,6 +328,7 @@ function callMatchesId(call: CallExpression, id: PatternId): boolean {
     case "readsConfig":
     case "systemScope":
     case "toggleable":
+    case "describe":
     case "config":
     case "translations":
     case "authClaims":

package/src/engine/feature-ast/patcher.ts

@@ -197,6 +197,7 @@ export type AddRequiresArgs = { readonly features: readonly string[] };
 export type AddOptionalRequiresArgs = { readonly features: readonly string[] };
 export type AddReadsConfigArgs = { readonly keys: readonly string[] };
 export type AddToggleableArgs = { readonly default: boolean };
+export type AddDescribeArgs = { readonly text: string };
 export type AddNavArgs = { readonly definition: NavDefinition };
 export type AddWorkspaceArgs = { readonly definition: WorkspaceDefinition };
 export type AddConfigArgs = {
@@ -223,6 +224,7 @@ export type FeaturePatcher = {
   readonly addReadsConfig: (args: AddReadsConfigArgs) => void;
   readonly addSystemScope: () => void;
   readonly addToggleable: (args: AddToggleableArgs) => void;
+  readonly addDescribe: (args: AddDescribeArgs) => void;
   readonly addEntity: (args: AddEntityArgs) => void;
   readonly addRelation: (args: AddRelationArgs) => void;
   readonly addNav: (args: AddNavArgs) => void;
@@ -300,6 +302,9 @@ export function createFeaturePatcher(sourceFile: SourceFile): FeaturePatcher {
     addToggleable({ default: defaultOn }) {
       add({ kind: "toggleable", source: SYNTHETIC_LOC, default: defaultOn });
     },
+    addDescribe({ text }) {
+      add({ kind: "describe", source: SYNTHETIC_LOC, text });
+    },
     addEntity({ name, definition }) {
       add({
         kind: "entity",

package/src/engine/feature-ast/patterns.ts

@@ -138,6 +138,12 @@ export type ToggleablePattern = {
   readonly default: boolean;
 };
 
+export type DescribePattern = {
+  readonly kind: "describe";
+  readonly source: SourceLocation;
+  readonly text: string;
+};
+
 export type MetricPattern = {
   readonly kind: "metric";
   readonly source: SourceLocation;
@@ -419,6 +425,7 @@ export type FeaturePattern =
   | OptionalRequiresPattern
   | SystemScopePattern
   | ToggleablePattern
+  | DescribePattern
   | MetricPattern
   | SecretPattern
   | ClaimKeyPattern
@@ -476,6 +483,7 @@ export function getEditability(pattern: FeaturePattern): Editability {
     case "optionalRequires":
     case "systemScope":
     case "toggleable":
+    case "describe":
     case "metric":
     case "secret":
     case "claimKey":

package/src/engine/feature-ast/render.ts

@@ -21,6 +21,7 @@ import type {
   ClaimKeyPattern,
   ConfigPattern,
   DefineEventPattern,
+  DescribePattern,
   EntityHookPattern,
   EntityPattern,
   EnvSchemaPattern,
@@ -77,6 +78,8 @@ export function renderPattern(pattern: FeaturePattern): string {
       return renderSystemScope(pattern);
     case "toggleable":
       return renderToggleable(pattern);
+    case "describe":
+      return renderDescribe(pattern);
     case "entity":
       return renderEntity(pattern);
     case "relation":
@@ -232,6 +235,10 @@ function renderToggleable(p: ToggleablePattern): string {
   return `r.toggleable({ default: ${p.default} });`;
 }
 
+function renderDescribe(p: DescribePattern): string {
+  return `r.describe(${JSON.stringify(p.text)});`;
+}
+
 function renderEntity(p: EntityPattern): string {
   // Inline `name` into the definition object — canonical Object-Form
   // is a single arg with name-as-property.

package/src/engine/pattern-library/__tests__/library.test.ts

@@ -30,6 +30,7 @@ const ALL_KINDS: FeaturePatternKind[] = [
   "readsConfig",
   "systemScope",
   "toggleable",
+  "describe",
   "entity",
   "relation",
   "nav",
@@ -197,6 +198,8 @@ function makePlaceholderPattern(kind: FeaturePatternKind): FeaturePattern {
       return { kind, source: PLACEHOLDER_LOC };
     case "toggleable":
       return { kind, source: PLACEHOLDER_LOC, default: false };
+    case "describe":
+      return { kind, source: PLACEHOLDER_LOC, text: "x" };
     case "entity":
       return { kind, source: PLACEHOLDER_LOC, entityName: "x", definition: { fields: {} } };
     case "relation":

package/src/engine/pattern-library/library.ts

@@ -176,6 +176,24 @@ const toggleableSchema: PatternFormSchema = {
   ],
 };
 
+const describeSchema: PatternFormSchema = {
+  kind: "describe",
+  label: { en: "Description", de: "Beschreibung" },
+  summary: { en: "One-to-three-sentence docs-lead: what the feature does + when you need it." },
+  category: "meta",
+  editability: "static",
+  singleton: true,
+  fields: [
+    {
+      path: "text",
+      label: { en: "Text", de: "Text" },
+      input: "textarea",
+      required: true,
+      placeholder: "Stores per-tenant widgets and exposes CRUD handlers for them.",
+    },
+  ],
+};
+
 const entitySchema: PatternFormSchema = {
   kind: "entity",
   label: { en: "Entity", de: "Entität" },
@@ -1142,6 +1160,7 @@ export const PATTERN_LIBRARY: Readonly<Record<FeaturePatternKind, PatternFormSch
   readsConfig: readsConfigSchema,
   systemScope: systemScopeSchema,
   toggleable: toggleableSchema,
+  describe: describeSchema,
   entity: entitySchema,
   relation: relationSchema,
   nav: navSchema,

package/src/engine/system-user.ts

@@ -7,11 +7,19 @@ import type { TenantId } from "./types/identifiers";
 export const SYSTEM_USER_ID = "00000000-0000-0000-0000-000000000000";
 export const SYSTEM_ROLE = "system" as const;
 
-export function createSystemUser(tenantId: TenantId): SessionUser {
+// extraRoles: hasAccess kennt keinen System-Bypass — Handler gaten auf
+// explizite Rollen. Caller, die Handler mit z.B. SystemAdmin-Gate erreichen
+// müssen (extraRoutes.dispatchSystemWrite → billing-foundation
+// process-event), geben die Rolle hier zusätzlich mit; createdBy bleibt
+// SYSTEM_USER_ID, der Audit-Trail zeigt weiterhin System.
+export function createSystemUser(
+  tenantId: TenantId,
+  extraRoles: readonly string[] = [],
+): SessionUser {
   return {
     id: SYSTEM_USER_ID,
     tenantId,
-    roles: [SYSTEM_ROLE],
+    roles: [SYSTEM_ROLE, ...extraRoles],
   };
 }
 

package/src/engine/types/feature.ts

@@ -170,6 +170,9 @@ export type UnmanagedTableDef = UnmanagedTableEntry & {
 
 export type FeatureDefinition = {
   readonly name: string;
+  // Docs-lead paragraph declared via r.describe(). Flows through the
+  // manifest introspection into the generated feature-reference pages.
+  readonly description?: string;
   readonly systemScope: boolean;
   // Set from the setup-callback return — typed via `defineFeature<TExports>`.
   // `undefined` for setups that return nothing.
@@ -335,6 +338,9 @@ export type RequiresApi = ((...featureNames: string[]) => void) & {
 
 export type FeatureRegistrar<TFeature extends string = string> = {
   systemScope(): void;
+  // One-to-three-sentence docs-lead for the feature ("what it does + when
+  // you need it"). At most once per feature; must be non-empty.
+  describe(text: string): void;
   requires: RequiresApi;
   optionalRequires(...featureNames: string[]): void;
   // Declare the feature as operator-togglable. `default` is the effective

package/src/entrypoint/index.ts

@@ -45,7 +45,7 @@ import type { Lifecycle } from "../lifecycle";
 import { createLifecycle } from "../lifecycle";
 import type { ObservabilityOptions, ObservabilityProvider } from "../observability";
 import type { EventDedup, EventDispatcher } from "../pipeline";
-import type { DispatcherOptions } from "../pipeline/dispatcher";
+import type { Dispatcher, DispatcherOptions } from "../pipeline/dispatcher";
 import type { SystemHooks } from "../pipeline/lifecycle-pipeline";
 
 // Shared fields across all three modes. A caller that swaps between
@@ -114,9 +114,12 @@ export type ApiEntrypoint = {
   readonly sseBroker: SseBroker;
   readonly lifecycle: Lifecycle;
   readonly observability: ObservabilityProvider;
+  // Command-dispatcher behind /api/* — for writes outside the HTTP
+  // pipeline (provider-webhook routes, see KumikoServer.dispatcher).
+  readonly dispatcher: Dispatcher;
   readonly mode: "api";
-  // No-op on API mode — dispatcher isn't built, job-runner doesn't exist.
-  // Kept for a uniform call-site so `main.ts` doesn't branch on mode.
+  // No-op on API mode — event-dispatcher isn't built, job-runner doesn't
+  // exist. Kept for a uniform call-site so `main.ts` doesn't branch on mode.
   start(): Promise<void>;
   stop(): Promise<void>;
 };
@@ -329,6 +332,7 @@ export function createApiEntrypoint(options: ApiEntrypointOptions): ApiEntrypoin
     sseBroker: server.sseBroker,
     lifecycle,
     observability: server.observability,
+    dispatcher: server.dispatcher,
     mode: "api",
     async start() {
       // Start the local BullMQ worker when runLocalJobs=true; enqueuer-only
@@ -424,6 +428,7 @@ export function createAllInOneEntrypoint(options: AllInOneEntrypointOptions): Al
     eventDispatcher,
     jobRunner: workerJobRunner,
     observability: server.observability,
+    dispatcher: server.dispatcher,
     mode: "all-in-one",
     async start() {
       await eventDispatcher.start();

package/src/files/feature.ts

@@ -16,6 +16,9 @@ export { fileRefEntity } from "./file-ref-entity";
 // file-routes + fileRefsTable; bundled-features/files re-exportiert nur.
 export function createFilesFeature(): FeatureDefinition {
   return defineFeature("files", (r) => {
+    r.describe(
+      "Exposes the `fileRef` entity and `createFilesFeature` from the framework core so that uploaded files \u2014 tracked in the `file_refs` table by `createFileRoutes` \u2014 participate in cross-feature hooks: `user-data-rights-defaults` automatically includes file blobs in GDPR exports and forget flows, and future tenant-lifecycle cleanup will delete all refs on tenant destroy. This feature does not add upload or download routes; those remain in the server bootstrap via the `options.files` parameter.",
+    );
     r.entity("fileRef", fileRefEntity);
   });
 }

package/src/stack/test-stack.ts

@@ -10,7 +10,7 @@ import type { FeatureDefinition, Registry, TenantId } from "../engine/types";
 import { createArchivedStreamsTable, createEventsTable } from "../event-store";
 import type { Lifecycle } from "../lifecycle";
 import type { ObservabilityProvider } from "../observability";
-import type { EventDispatcher } from "../pipeline";
+import type { Dispatcher, EventDispatcher } from "../pipeline";
 import { createEntityCache, createEventDedup, createIdempotencyGuard } from "../pipeline";
 import { createInMemorySearchAdapter } from "../search";
 import type { SearchAdapter } from "../search/types";
@@ -31,6 +31,9 @@ export type TestStack = {
   events: EventCollector;
   http: RequestHelper;
   observability: ObservabilityProvider;
+  // Command-dispatcher behind the HTTP routes — for direct system-writes
+  // in tests and dev-server extraRoutes (provider-webhook wiring).
+  dispatcher: Dispatcher;
   // Present whenever a system consumer (SSE, Search) or
   // r.multiStreamProjection is wired. Tests drain it via runOnce() for
   // deterministic assertion — no timer-induced flakiness.
@@ -355,6 +358,7 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
     events,
     http,
     observability: server.observability,
+    dispatcher: server.dispatcher,
     ...(eventDispatcher ? { eventDispatcher } : {}),
     ...(server.lifecycle ? { lifecycle: server.lifecycle } : {}),
     cleanup: async () => {