@cosmicdrift/kumiko-framework 0.177.0 → 0.178.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.177.0",
+  "version": "0.178.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>",
@@ -182,7 +182,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.177.0",
+    "@cosmicdrift/kumiko-types": "0.178.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.12.27",
@@ -198,7 +198,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.177.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.178.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/engine/__tests__/content-collection.test.ts

@@ -0,0 +1,212 @@
+// r.contentCollection() — sugar over r.nav() that also records which
+// template-resource kind the node lists, so the client can derive the tree
+// provider instead of the app repeating navId + kind.
+
+import { describe, expect, test } from "bun:test";
+import { withBootValidatorFixture } from "../../testing/boot-validator-fixture";
+import { validateBoot as validateBootRaw } from "../boot-validator";
+import { buildAppSchema } from "../build-app-schema";
+import { defineFeature } from "../define-feature";
+import { createRegistry } from "../registry";
+
+function validateBoot(features: Parameters<typeof validateBootRaw>[0]): void {
+  validateBootRaw(withBootValidatorFixture(features));
+}
+
+describe("r.contentCollection() — registration", () => {
+  test("registers a nav entry with provider:true and returns its qualified name", () => {
+    let qn = "";
+    const feature = defineFeature("mail", (r) => {
+      qn = r.contentCollection({
+        id: "templates",
+        kind: "mail-html",
+        nav: { label: "mail:nav.templates", icon: "file" },
+      });
+    });
+
+    expect(qn).toBe("mail:nav:templates");
+    // The children arrive from a runtime provider — without provider:true the
+    // node would render as an empty leaf.
+    expect(feature.navs["templates"]?.provider).toBe(true);
+    expect(feature.navs["templates"]?.label).toBe("mail:nav.templates");
+    expect(feature.navs["templates"]?.icon).toBe("file");
+    expect(feature.contentCollections?.["templates"]?.kind).toBe("mail-html");
+  });
+
+  test("passes nav placement through: parent, order, access, workspaces", () => {
+    const feature = defineFeature("mail", (r) => {
+      r.nav({ id: "root", label: "mail:nav.root" });
+      r.contentCollection({
+        id: "templates",
+        kind: "mail-html",
+        nav: {
+          label: "mail:nav.templates",
+          parent: "mail:nav:root",
+          order: 20,
+          access: { roles: ["TenantAdmin"] },
+          workspaces: ["mail:workspace:ops"],
+        },
+      });
+    });
+
+    const nav = feature.navs["templates"];
+    expect(nav?.parent).toBe("mail:nav:root");
+    expect(nav?.order).toBe(20);
+    expect(nav?.access).toEqual({ roles: ["TenantAdmin"] });
+    expect(nav?.workspaces).toEqual(["mail:workspace:ops"]);
+  });
+
+  test("passes createAction and hover actions through to the nav entry", () => {
+    const target = { featureId: "template-resolver", action: "create", args: { folder: "" } };
+    const feature = defineFeature("mail", (r) => {
+      r.contentCollection({
+        id: "templates",
+        kind: "mail-html",
+        nav: {
+          label: "mail:nav.templates",
+          createAction: { label: "mail:action.new", icon: "plus", target },
+          actions: [{ label: "mail:action.list", icon: "list", target }],
+        },
+      });
+    });
+
+    // Without these a collection can only list what already exists — the "+"
+    // affordance is the whole authoring entry point.
+    expect(feature.navs["templates"]?.createAction?.label).toBe("mail:action.new");
+    expect(feature.navs["templates"]?.actions).toHaveLength(1);
+  });
+
+  test("the nav node inherits the collection's access — no node the handler would refuse", () => {
+    const feature = defineFeature("mail", (r) => {
+      r.contentCollection({
+        id: "prompts",
+        kind: "ai-prompt",
+        access: { roles: ["PromptEngineer"] },
+        nav: { label: "mail:nav.prompts" },
+      });
+    });
+
+    expect(feature.navs["prompts"]?.access).toEqual({ roles: ["PromptEngineer"] });
+  });
+
+  test("an explicit nav.access still wins over the collection's", () => {
+    const feature = defineFeature("mail", (r) => {
+      r.contentCollection({
+        id: "prompts",
+        kind: "ai-prompt",
+        access: { roles: ["PromptEngineer"] },
+        nav: { label: "mail:nav.prompts", access: { roles: ["TenantAdmin"] } },
+      });
+    });
+
+    expect(feature.navs["prompts"]?.access).toEqual({ roles: ["TenantAdmin"] });
+  });
+
+  test("records ownership so the handlers can scope reads", () => {
+    const feature = defineFeature("mail", (r) => {
+      r.contentCollection({
+        id: "signatures",
+        kind: "mail-html",
+        ownership: "user",
+        nav: { label: "mail:nav.signatures" },
+      });
+    });
+
+    expect(feature.contentCollections?.["signatures"]?.ownership).toBe("user");
+  });
+
+  test("rejects a second collection with the same id", () => {
+    expect(() =>
+      defineFeature("mail", (r) => {
+        r.contentCollection({ id: "templates", kind: "mail-html", nav: { label: "a" } });
+        r.contentCollection({ id: "templates", kind: "ai-prompt", nav: { label: "b" } });
+      }),
+    ).toThrow(/already registered/);
+  });
+
+  test("rejects an id already taken by a plain r.nav()", () => {
+    expect(() =>
+      defineFeature("mail", (r) => {
+        r.nav({ id: "templates", label: "mail:nav.templates" });
+        r.contentCollection({ id: "templates", kind: "mail-html", nav: { label: "b" } });
+      }),
+    ).toThrow(/already registered/);
+  });
+
+  test("rejects a non-kebab id", () => {
+    expect(() =>
+      defineFeature("mail", (r) => {
+        r.contentCollection({ id: "MailTemplates", kind: "mail-html", nav: { label: "a" } });
+      }),
+    ).toThrow(/kebab-case/);
+  });
+});
+
+describe("r.contentCollection() — boot validation", () => {
+  test("a collection mounted under another feature's nav passes", () => {
+    const mail = defineFeature("mail", (r) => {
+      r.nav({ id: "root", label: "mail:nav.root" });
+    });
+    const templates = defineFeature("templates", (r) => {
+      r.contentCollection({
+        id: "mail-templates",
+        kind: "mail-html",
+        nav: { label: "templates:nav.mail", parent: "mail:nav:root" },
+      });
+    });
+
+    expect(() => validateBoot([mail, templates])).not.toThrow();
+  });
+
+  test("a dangling parent fails boot instead of silently vanishing from the sidebar", () => {
+    const templates = defineFeature("templates", (r) => {
+      r.contentCollection({
+        id: "mail-templates",
+        kind: "mail-html",
+        nav: { label: "templates:nav.mail", parent: "mail:nav:root" },
+      });
+    });
+
+    expect(() => validateBoot([templates])).toThrow(/mail:nav:root/);
+  });
+});
+
+describe("buildAppSchema — content collections", () => {
+  test("projects collections with the nav QN qualified", () => {
+    const registry = createRegistry([
+      defineFeature("mail", (r) => {
+        r.nav({ id: "root", label: "mail:nav.root" });
+        r.contentCollection({
+          id: "templates",
+          kind: "mail-html",
+          nav: { label: "mail:nav.templates", parent: "mail:nav:root" },
+        });
+      }),
+    ]);
+
+    const schema = buildAppSchema(registry);
+    const mail = schema.features.find((f) => f.featureName === "mail");
+    expect(mail?.contentCollections).toEqual([
+      {
+        id: "templates",
+        kind: "mail-html",
+        nav: { label: "mail:nav.templates", parent: "mail:nav:root" },
+        navQn: "mail:nav:templates",
+      },
+    ]);
+    // The nav entry itself still travels the normal route — the collection
+    // list only carries what a NavDefinition cannot express.
+    expect(mail?.navs?.map((n) => n.id)).toContain("templates");
+  });
+
+  test("omits the slot for features without collections", () => {
+    const registry = createRegistry([
+      defineFeature("shop", (r) => {
+        r.nav({ id: "catalog", label: "shop:nav.catalog" });
+      }),
+    ]);
+
+    const shop = buildAppSchema(registry).features.find((f) => f.featureName === "shop");
+    expect(shop?.contentCollections).toBeUndefined();
+  });
+});

package/src/engine/build-app-schema.ts

@@ -46,11 +46,21 @@ export function buildAppSchema(registry: Registry, options: BuildAppSchemaOption
   const features: FeatureSchema[] = [];
   for (const [featureName, feature] of registry.features) {
     const navs = Object.values(feature.navs);
+    // The nav entry alone doesn't say which kind a collection lists, so the
+    // client can't derive its tree provider from `navs` — project the
+    // collections separately, with the nav QN already qualified.
+    const contentCollections = Object.values(feature.contentCollections ?? {}).map(
+      (collection) => ({
+        ...collection,
+        navQn: `${featureName}:nav:${collection.id}`,
+      }),
+    );
     const featureSchema: FeatureSchema = {
       featureName,
       entities: projectEntities(feature.entities ?? {}),
       screens: Object.values(feature.screens),
       ...(navs.length > 0 && { navs }),
+      ...(contentCollections.length > 0 && { contentCollections }),
       // #1059: verbatim r.translations({keys}) — see FeatureSchema.translations
       // doc for why this must NOT go through registry.getAllTranslations()
       // (double-prefixes features that already qualify their own keys).

package/src/engine/define-feature.ts

@@ -152,6 +152,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     claimKeys: state.claimKeys,
     screens: state.screens,
     navs: state.navs,
+    contentCollections: state.contentCollections,
     workspaces: state.workspaces,
     httpRoutes: state.httpRoutes,
     storeTables: state.storeTables,

package/src/engine/feature-builder-state.ts

@@ -38,7 +38,7 @@ import type {
   WriteHandlerDef,
 } from "./types";
 import type { HttpRouteDefinition } from "./types/http-route";
-import type { NavDefinition } from "./types/nav";
+import type { ContentCollectionDefinition, NavDefinition } from "./types/nav";
 import type { ScreenDefinition } from "./types/screen";
 import type { WorkspaceDefinition } from "./types/workspace";
 
@@ -95,6 +95,7 @@ export type FeatureBuilderState = {
   claimKeys: Record<string, ClaimKeyDefinition>;
   screens: Record<string, ScreenDefinition>;
   navs: Record<string, NavDefinition>;
+  contentCollections: Record<string, ContentCollectionDefinition>;
   workspaces: Record<string, WorkspaceDefinition>;
   httpRoutes: Record<string, HttpRouteDefinition>;
   translations: TranslationKeys;
@@ -155,6 +156,7 @@ export function createInitialFeatureBuilderState(): FeatureBuilderState {
     claimKeys: {},
     screens: {},
     navs: {},
+    contentCollections: {},
     workspaces: {},
     httpRoutes: {},
     translations: {},

package/src/engine/feature-ui-extensions.ts

@@ -25,7 +25,7 @@ import type {
 } from "./types";
 import { HookPhases } from "./types";
 import type { HttpRouteDefinition } from "./types/http-route";
-import type { NavDefinition } from "./types/nav";
+import type { ContentCollectionDefinition, NavDefinition } from "./types/nav";
 import type { ScreenDefinition } from "./types/screen";
 import type { WorkspaceDefinition } from "./types/workspace";
 
@@ -373,6 +373,41 @@ export function buildUiExtensionsMethods<TName extends string>(
     nav(definition: NavDefinition): void {
       registerNav(definition);
     },
+    contentCollection(definition: ContentCollectionDefinition): string {
+      if (state.contentCollections[definition.id]) {
+        throw new Error(
+          `[Feature ${name}] Content collection "${definition.id}" already registered. ` +
+            `Collection ids must be unique per feature.`,
+        );
+      }
+      // registerNav owns the kebab + collision checks, including collisions
+      // with a plain r.nav() of the same id. Optional fields stay absent
+      // rather than explicitly undefined — buildAppSchema's JSON-safety check
+      // flags undefined values.
+      registerNav({
+        id: definition.id,
+        label: definition.nav.label,
+        ...(definition.nav.icon !== undefined && { icon: definition.nav.icon }),
+        ...(definition.nav.parent !== undefined && { parent: definition.nav.parent }),
+        ...(definition.nav.order !== undefined && { order: definition.nav.order }),
+        // Nav visibility follows the collection's access unless the caller
+        // overrode it — a node the handler would refuse has no business in
+        // the sidebar.
+        ...((definition.nav.access ?? definition.access) !== undefined && {
+          access: definition.nav.access ?? definition.access,
+        }),
+        ...(definition.nav.workspaces !== undefined && { workspaces: definition.nav.workspaces }),
+        ...(definition.nav.createAction !== undefined && {
+          createAction: definition.nav.createAction,
+        }),
+        ...(definition.nav.actions !== undefined && { actions: definition.nav.actions }),
+        // The tree children come from a runtime provider keyed on this QN —
+        // a collection without it would render as an empty leaf.
+        provider: true,
+      });
+      state.contentCollections[definition.id] = definition;
+      return `${name}:nav:${definition.id}`;
+    },
     workspace(definition: WorkspaceDefinition): void {
       // Same kebab guard as r.screen / r.nav so authoring-time mistakes
       // surface at the feature file, not deep in registry boot.

package/src/engine/index.ts

@@ -292,6 +292,7 @@ export type {
   ConfigValue,
   ConfigValueSource,
   ConfigValueWithSource,
+  ContentCollectionDefinition,
   CreateSeedOptions,
   CreateTenantSeedOptions,
   CreateUserSeedOptions,

package/src/engine/types/index.ts

@@ -206,7 +206,7 @@ export {
   parseTenantId,
   SYSTEM_TENANT_ID,
 } from "@cosmicdrift/kumiko-types/identifiers";
-export type { NavDefinition } from "@cosmicdrift/kumiko-types/nav";
+export type { ContentCollectionDefinition, NavDefinition } from "@cosmicdrift/kumiko-types/nav";
 export type {
   FromRule,
   FromRuleKind,

package/src/ui-types/app-schema.ts

@@ -9,7 +9,7 @@
 
 import type { TranslationKeys } from "../engine/types/config";
 import type { EntityDefinition } from "../engine/types/fields";
-import type { NavDefinition } from "../engine/types/nav";
+import type { ContentCollectionDefinition, NavDefinition } from "../engine/types/nav";
 import type { ScreenDefinition } from "../engine/types/screen";
 import type { WorkspaceDefinition } from "../engine/types/workspace";
 
@@ -20,6 +20,12 @@ export type FeatureSchema = {
   // Flat list; resolveNavigation builds the tree at render-time from
   // the registry's indexes. Omitted when the app has no top-level nav.
   readonly navs?: readonly NavDefinition[];
+  // Content collections declared via r.contentCollection(), each with its nav
+  // QN already qualified. The matching nav entries are in `navs` like any
+  // other; this list only carries what a NavDefinition can't express — which
+  // template-resource `kind` the node lists — so the client can build one
+  // tree provider per collection. Omitted when a feature declares none.
+  readonly contentCollections?: readonly QualifiedContentCollection[];
   // Server-authored `r.translations({ keys })`, projected verbatim — byte-
   // identical keys, NOT re-prefixed with featureName (unlike the registry's
   // internal mergedTranslations, which double-prefixes features that
@@ -39,6 +45,12 @@ export type FeatureSchema = {
   readonly workspaces?: readonly WorkspaceSchema[];
 };
 
+// A content collection as it reaches the client: the declaration plus the
+// already-qualified nav QN, so consumers don't rebuild "<feature>:nav:<id>".
+export type QualifiedContentCollection = ContentCollectionDefinition & {
+  readonly navQn: string;
+};
+
 // Per-workspace projection of the engine's WorkspaceDefinition + the
 // pre-resolved member nav QNs. The shell renders the switcher from
 // `definition` and filters the nav tree using `navMembers`.

package/src/ui-types/index.ts

@@ -91,4 +91,9 @@ export type { TargetRef } from "../engine/types/target-ref";
 export type { TreeAction, TreeNode, TreeNodeState } from "../engine/types/tree-node";
 export type { WorkspaceDefinition } from "../engine/types/workspace";
 export { PROJECTION_DETAIL_ENTITY } from "../i18n/required-surface-keys";
-export type { AppSchema, FeatureSchema, WorkspaceSchema } from "./app-schema";
+export type {
+  AppSchema,
+  FeatureSchema,
+  QualifiedContentCollection,
+  WorkspaceSchema,
+} from "./app-schema";