@cosmicdrift/kumiko-framework 0.71.0 → 0.72.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.71.0",
+  "version": "0.72.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>",
@@ -181,7 +181,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.71.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.72.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

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

@@ -241,6 +241,39 @@ describe("defineFeature", () => {
 
     expect(rolesOf(feature.writeHandlers["user:invite"]?.access)).toEqual(["Admin", "SystemAdmin"]);
   });
+
+  test("r.uiHints() flows into the definition", () => {
+    const feature = defineFeature("test", (r) => {
+      r.uiHints({
+        displayLabel: "Test Feature",
+        category: "demo",
+        recommended: true,
+        configurableOptions: [
+          { key: "fancy", label: "Fancy mode", type: "boolean", default: false },
+        ],
+      });
+    });
+    expect(feature.uiHints?.displayLabel).toBe("Test Feature");
+    expect(feature.uiHints?.category).toBe("demo");
+    expect(feature.uiHints?.recommended).toBe(true);
+    expect(feature.uiHints?.configurableOptions).toEqual([
+      { key: "fancy", label: "Fancy mode", type: "boolean", default: false },
+    ]);
+  });
+
+  test("uiHints is absent when r.uiHints() is not called", () => {
+    const feature = defineFeature("test", () => {});
+    expect("uiHints" in feature).toBe(false);
+  });
+
+  test("r.uiHints() throws when called twice", () => {
+    expect(() =>
+      defineFeature("test", (r) => {
+        r.uiHints({ displayLabel: "A" });
+        r.uiHints({ displayLabel: "B" });
+      }),
+    ).toThrow(/r\.uiHints\(\) called twice/);
+  });
 });
 
 // --- Field Factories ---

package/src/engine/__tests__/feature-manifest.test.ts

@@ -84,4 +84,24 @@ describe("buildManifestFromRegistry — deterministic codepoint sort (#330)", ()
     expect(manifest.tier).toBeUndefined();
     expect(manifest.features[0]?.tier).toBeUndefined();
   });
+
+  test("uiHints flow through to the manifest when set", () => {
+    const registry = createRegistry([
+      defineFeature("with-hints", (r) => {
+        r.uiHints({ displayLabel: "With Hints", category: "demo", recommended: true });
+      }),
+      defineFeature("no-hints", () => {}),
+    ]);
+
+    const manifest = buildManifestFromRegistry(registry, { source: "test" });
+    const withHints = manifest.features.find((f) => f.name === "with-hints");
+    const noHints = manifest.features.find((f) => f.name === "no-hints");
+
+    expect(withHints?.uiHints).toEqual({
+      displayLabel: "With Hints",
+      category: "demo",
+      recommended: true,
+    });
+    expect(noHints && "uiHints" in noHints).toBe(false);
+  });
 });

package/src/engine/define-feature.ts

@@ -63,6 +63,7 @@ import type {
   TreeActionDef,
   TreeActionsHandle,
   TreeChildrenSubscribe,
+  UiHints,
   UnmanagedTableEntry,
   ValidationHookFn,
   WriteHandlerDef,
@@ -157,6 +158,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
   let isSystemScoped = false;
   let toggleableDefault: boolean | undefined;
   let description: string | undefined;
+  let uiHints: UiHints | 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).
@@ -240,6 +242,13 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       toggleableDefault = options.default;
     },
 
+    uiHints(hints: UiHints): void {
+      if (uiHints !== undefined) {
+        throw new Error(`[Feature ${name}] r.uiHints() called twice — UI hints are declared once`);
+      }
+      uiHints = hints;
+    },
+
     entity(
       entityName: string,
       definition: EntityDefinition,
@@ -944,6 +953,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     requiredProjections,
     requiredSteps,
     ...(toggleableDefault !== undefined && { toggleableDefault }),
+    ...(uiHints !== undefined && { uiHints }),
     entities,
     entityTables,
     relations,

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

@@ -5,6 +5,7 @@ export {
   extractRequires,
   extractSystemScope,
   extractToggleable,
+  extractUiHints,
 } from "./round1";
 export {
   extractEntity,

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

@@ -6,6 +6,7 @@ import type {
   RequiresPattern,
   SystemScopePattern,
   ToggleablePattern,
+  UiHintsPattern,
 } from "../patterns";
 import { sourceLocationFromNode } from "../source-location";
 import {
@@ -84,6 +85,16 @@ export function extractSystemScope(
   });
 }
 
+export function extractUiHints(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<UiHintsPattern> {
+  return ok({
+    kind: "uiHints",
+    source: sourceLocationFromNode(call, sourceFile),
+  });
+}
+
 export function extractDescribe(
   call: CallExpression,
   sourceFile: SourceFile,

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

@@ -58,6 +58,7 @@ import {
   extractTranslations,
   extractTree,
   extractTreeActions,
+  extractUiHints,
   extractUnmanagedTable,
   extractUseExtension,
   extractUsesApi,
@@ -301,6 +302,8 @@ function dispatchExtractor(
       return extractToggleable(call, sourceFile);
     case "describe":
       return extractDescribe(call, sourceFile);
+    case "uiHints":
+      return extractUiHints(call, sourceFile);
     // Round 2 — object-literal-based static patterns
     case "entity":
       return extractEntity(call, sourceFile);

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

@@ -80,6 +80,7 @@ export type PatternId =
   | { readonly kind: "systemScope" }
   | { readonly kind: "toggleable" }
   | { readonly kind: "describe" }
+  | { readonly kind: "uiHints" }
   | { readonly kind: "config" }
   | { readonly kind: "translations" }
   | { readonly kind: "authClaims" }
@@ -272,6 +273,7 @@ export const SINGLETON_KINDS: ReadonlySet<PatternId["kind"]> = new Set([
   "systemScope",
   "toggleable",
   "describe",
+  "uiHints",
   "config",
   "translations",
   "authClaims",
@@ -329,6 +331,7 @@ function callMatchesId(call: CallExpression, id: PatternId): boolean {
     case "systemScope":
     case "toggleable":
     case "describe":
+    case "uiHints":
     case "config":
     case "translations":
     case "authClaims":

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

@@ -203,6 +203,16 @@ export type DescribePattern = {
   readonly text: string;
 };
 
+// `r.uiHints({ displayLabel, category, recommended, configurableOptions })` —
+// picker/scaffolder UI metadata that flows into feature-manifest.json under
+// `feature.uiHints`. Tracked as opaque here (no structured re-parse): the
+// picker reads the manifest, not the AST. The pattern exists so the
+// UnknownPattern dispatcher doesn't trip on a new r.* call.
+export type UiHintsPattern = {
+  readonly kind: "uiHints";
+  readonly source: SourceLocation;
+};
+
 // `r.metric(shortName, options)` — declares a metric under its short name
 // (without the `kumiko_<feature>_` prefix; the framework qualifies it at
 // boot and validates snake_case + type suffix). Runtime usage:
@@ -590,6 +600,7 @@ export type FeaturePattern =
   | SystemScopePattern
   | ToggleablePattern
   | DescribePattern
+  | UiHintsPattern
   | MetricPattern
   | SecretPattern
   | ClaimKeyPattern
@@ -675,6 +686,7 @@ export function getEditability(pattern: FeaturePattern): Editability {
     case "extendsRegistrar":
     case "tree":
     case "envSchema":
+    case "uiHints":
     case "unknown":
       return "opaque";
     default: {

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

@@ -50,6 +50,7 @@ import type {
   TranslationsPattern,
   TreeActionsPattern,
   TreePattern,
+  UiHintsPattern,
   UnknownPattern,
   UseExtensionPattern,
   UsesApiPattern,
@@ -80,6 +81,8 @@ export function renderPattern(pattern: FeaturePattern): string {
       return renderToggleable(pattern);
     case "describe":
       return renderDescribe(pattern);
+    case "uiHints":
+      return renderUiHints(pattern);
     case "entity":
       return renderEntity(pattern);
     case "relation":
@@ -517,6 +520,10 @@ function renderExposesApi(p: ExposesApiPattern): string {
   return `r.exposesApi(${JSON.stringify(p.apiName)});`;
 }
 
+function renderUiHints(p: UiHintsPattern): string {
+  return p.source.raw;
+}
+
 function renderUnknown(p: UnknownPattern): string {
   // Round-trip preservation only: emit the raw call text from the
   // SourceLocation so the rendered file stays semantically identical

package/src/engine/feature-manifest.ts

@@ -8,7 +8,7 @@
 
 import { compareByCodepoint } from "../utils";
 import { qualifyEntityName } from "./qualified-name";
-import type { Registry } from "./types/feature";
+import type { Registry, UiHints } from "./types/feature";
 
 export type ManifestConfigKey = {
   readonly key: string;
@@ -57,6 +57,10 @@ export type ManifestFeature = {
    *  Von `collectWriteHandlerQns` abgeleitet — dient als Source-of-Truth
    *  für den Client-seitigen Typcheck von `dispatcher.write`-Calls. */
   readonly writeHandlers: readonly string[];
+  /** Picker/scaffolder UI metadata declared via r.uiHints(). Optional —
+   *  absent for features that haven't been annotated yet (the picker falls
+   *  back to feature.name + feature.description). */
+  readonly uiHints?: UiHints;
   /** Optionaler Herkunfts-Tag (z.B. "enterprise") — gesetzt via Options. */
   readonly tier?: string;
 };
@@ -148,6 +152,7 @@ export function buildManifestFromRegistry(
       configKeys,
       secrets,
       writeHandlers: writeHandlerQns,
+      ...(feature.uiHints !== undefined && { uiHints: feature.uiHints }),
       ...(options.tier !== undefined && { tier: options.tier }),
     });
   }

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

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

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

@@ -194,6 +194,16 @@ const describeSchema: PatternFormSchema = {
   ],
 };
 
+const uiHintsSchema: PatternFormSchema = {
+  kind: "uiHints",
+  label: { en: "UI hints", de: "UI-Hinweise" },
+  summary: { en: "Picker/scaffolder metadata. Opaque to the Designer; rendered as raw TS source." },
+  category: "meta",
+  editability: "opaque",
+  singleton: true,
+  fields: [],
+};
+
 const entitySchema: PatternFormSchema = {
   kind: "entity",
   label: { en: "Entity", de: "Entität" },
@@ -1161,6 +1171,7 @@ export const PATTERN_LIBRARY: Readonly<Record<FeaturePatternKind, PatternFormSch
   systemScope: systemScopeSchema,
   toggleable: toggleableSchema,
   describe: describeSchema,
+  uiHints: uiHintsSchema,
   entity: entitySchema,
   relation: relationSchema,
   nav: navSchema,

package/src/engine/types/feature.ts

@@ -171,6 +171,51 @@ export type UnmanagedTableDef = UnmanagedTableEntry & {
   readonly featureName: string;
 };
 
+// --- UI-Hints (manifest-only, picker/scaffolder metadata) ---
+
+// Optional, declarative UI metadata declared via `r.uiHints({...})`. Surfaces
+// in feature-manifest.json under `feature.uiHints`. Consumers (the picker in
+// `create-kumiko-app`, the docs feature-reference) treat absent hints as
+// "no special treatment" — bare feature.name + feature.description still work.
+//
+// Keep this list lean. Anything that already has a home on the feature
+// (configKeys.scope/default/encrypted, secretKeys, requires, etc.) lives there.
+// Only add fields here that are genuinely UI-only.
+export type UiHintOption =
+  | {
+      readonly key: string;
+      readonly label: string;
+      readonly type: "boolean";
+      readonly default: boolean;
+    }
+  | {
+      readonly key: string;
+      readonly label: string;
+      readonly type: "select";
+      readonly options: readonly string[];
+      readonly default: string;
+    }
+  | {
+      readonly key: string;
+      readonly label: string;
+      readonly type: "text";
+      readonly default?: string;
+    };
+
+export type UiHints = {
+  // Picker-facing label ("Auth · Email + Password" instead of the bare
+  // feature-name "auth-email-password").
+  readonly displayLabel?: string;
+  // Grouping for the picker. Free-form string; the picker sorts/groups by it.
+  readonly category?: string;
+  // Pre-checked in the picker when the user runs `bun create kumiko-app`.
+  readonly recommended?: boolean;
+  // Sub-options the picker asks about per-feature (e.g. "Password-Reset-Flow
+  // on/off"). The scaffolder maps each key to a generator decision; the
+  // framework doesn't act on them at runtime.
+  readonly configurableOptions?: readonly UiHintOption[];
+};
+
 // --- Feature Definition (output of defineFeature) ---
 
 export type FeatureDefinition = {
@@ -197,6 +242,9 @@ export type FeatureDefinition = {
   // means the feature is always-on (e.g. auth, tenant, user — core infra
   // that would brick the system if switchable).
   readonly toggleableDefault?: boolean;
+  // Declarative UI metadata for picker/scaffolder tooling. Set via r.uiHints().
+  // Pure manifest-side info — the framework runtime doesn't read it.
+  readonly uiHints?: UiHints;
   // entities/hooks/entityHooks are optional: defineFeature always
   // materializes them, but hand-built definitions at system boundaries
   // (test fixtures, partial boots — see registry.test.ts "slot robustness")
@@ -365,6 +413,8 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   // feature; calling on an always-on feature (e.g. auth/tenant/user) is a
   // bug — and one nothing catches at boot, so don't.
   toggleable(options: { default: boolean }): void;
+  // Picker/scaffolder metadata — see UiHints. At most once per feature.
+  uiHints(hints: UiHints): void;
 
   entity(
     name: string,

package/src/engine/types/index.ts

@@ -74,6 +74,8 @@ export type {
   SecretKeyDefinition,
   SecretKeyHandle,
   SecretOptions,
+  UiHintOption,
+  UiHints,
   UnmanagedTableDef,
   UnmanagedTableEntry,
 } from "./feature";

package/src/files/__tests__/storage-tracking.integration.test.ts

@@ -200,3 +200,28 @@ describe("tenant-storage-usage MSP", () => {
     ).toBeGreaterThanOrEqual(0);
   });
 });
+
+// The MSP tests above prove upload *accounting*; nothing asserts the file
+// actually comes back. This pins the full HTTP read path (GET /files/:id →
+// provider readStream → response body) — the user-facing roundtrip.
+describe("file download roundtrip (GET /files/:id)", () => {
+  async function download(user: SessionUser, id: string): Promise<Response> {
+    const token = await stack.jwt.sign(user);
+    return stack.app.request(`/api/files/${id}`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+  }
+
+  test("returns the exact bytes that were uploaded", async () => {
+    const id = await upload(admin, "roundtrip.png", LARGE);
+    const res = await download(admin, id);
+    expect(res.status).toBe(200);
+    expect(new Uint8Array(await res.arrayBuffer())).toEqual(LARGE);
+  });
+
+  test("a deleted file is no longer downloadable", async () => {
+    const id = await upload(admin, "gone.png", SMALL);
+    await deleteFile(admin, id);
+    expect((await download(admin, id)).status).toBe(404);
+  });
+});

package/src/files/feature.ts

@@ -19,6 +19,11 @@ export function createFilesFeature(): FeatureDefinition {
     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.uiHints({
+      displayLabel: "Files \u00b7 Metadata",
+      category: "storage",
+      recommended: false,
+    });
     r.entity("fileRef", fileRefEntity);
   });
 }

package/src/utils/__tests__/ids.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, test } from "bun:test";
+import { generateId } from "../ids";
+
+// generateId is the row/stream/correlation ID source. The callers rely on
+// it being a UUIDv7 (time-sortable → dense B-Tree indexes), not a v4 — a
+// swap to v4 would silently kill the lexicographic-time ordering the event
+// store and time-range queries depend on. These tests pin that contract.
+const UUID_RX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+describe("generateId", () => {
+  test("returns a well-formed lowercase UUID", () => {
+    expect(generateId()).toMatch(UUID_RX);
+  });
+
+  test("is UUID version 7 (time-sortable, not v4)", () => {
+    // Version nibble lives in the 13th hex digit (index 14 incl. dashes).
+    expect(generateId()[14]).toBe("7");
+  });
+
+  test("is collision-free across a batch", () => {
+    const ids = Array.from({ length: 10_000 }, generateId);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+});