@stardeck-customer-apps/compose 0.7.0 → 0.8.0

package/SKILL.md

@@ -14,6 +14,8 @@ Compose turns that declaration into the code Next.js actually builds:
 - `apps/web/src/module-i18n.gen.ts`
 - `apps/web/src/module-init.server.gen.ts`
 - `apps/web/src/module-datastores.gen.ts`
+- `apps/web/src/module-server.gen.ts` — `MODULE_SERVER_REGISTRATIONS`, one entry
+  per composed Module that ships `server/registrations.ts`
 - one `page.tsx` / `route.ts` stub under `apps/web/src/app/**` per declared
   mount and endpoint
 
@@ -101,6 +103,19 @@ a silent fallback. It holds deployment facts: gitignore it (`apps/web/.gitignore
   compose as a route collision.
   `isMountHeadless(key)` and `isHrefHeadless(href)` are exported from
   `@/modules.gen`. Needs compose 0.7.0 or later.
+- **Server registrations.** Per-Module server wiring that the app layer runs
+  (seeds, schedule handlers, and similar) goes in the Module's
+  `server/registrations.ts`, any Module kind. Compose imports each composed
+  Module's file as a namespace into `module-server.gen.ts`:
+  `MODULE_SERVER_REGISTRATIONS` is a
+  `readonly { module: string; registrations: Readonly<Record<string, unknown>> }[]`.
+  A Module left out by `--enabled` is not imported at all, so its server code
+  drops out of the build. App code reads that array from `@/module-server.gen`
+  and narrows the exports it expects (e.g. `registrations.seed`); it must never
+  import a Module's seed or schedules directly, or a disabled Module stays in
+  the bundle. Compose does not check the export names or shapes. The file
+  counts as `server/**/*.ts`, so the Module also needs `server/index.ts`.
+  Needs compose 0.8.0 or later.
 - `@stardeck-customer-apps/compose/runtime` exports `isModuleEnabledByList`,
   the single enablement rule, and imports nothing — it is safe in client
   components.
@@ -111,5 +126,5 @@ After each run compose rewrites `apps/web/src/app/.gitignore` with one entry per
 stub it emits — stubs are scattered one-per-route and cannot be globbed. Commit
 that file: it is deterministic output, and compose rewrites it only when the set
 of stubs changes, so an unchanged compose leaves `git status` clean. It does not
-list the five `src/*.gen.ts`; a static `src/*.gen.ts` line in `apps/web/.gitignore`
+list the six `src/*.gen.ts`; a static `src/*.gen.ts` line in `apps/web/.gitignore`
 covers those. Compose refuses to touch the file if line 1 is not its own header.

package/dist/cli.js

@@ -3896,6 +3896,7 @@ var MODULE_CONTRIBUTIONS_GEN_PATH = `${APP_WEB_PREFIX}src/module-contributions.g
 var MODULE_DATASTORES_GEN_PATH = `${APP_WEB_PREFIX}src/module-datastores.gen.ts`;
 var MODULE_I18N_GEN_PATH = `${APP_WEB_PREFIX}src/module-i18n.gen.ts`;
 var MODULE_INIT_SERVER_GEN_PATH = `${APP_WEB_PREFIX}src/module-init.server.gen.ts`;
+var MODULE_SERVER_GEN_PATH = `${APP_WEB_PREFIX}src/module-server.gen.ts`;
 var MODULES_GEN_PATH = `${APP_WEB_PREFIX}src/modules.gen.ts`;
 var APP_EXTENSIONS_PATH = `${APP_WEB_PREFIX}src/lib/modules/app-extensions.ts`;
 
@@ -4141,7 +4142,8 @@ var COMPOSITION_RUNTIME_GEN_PATHS = [
   MODULE_CONTRIBUTIONS_GEN_PATH,
   MODULE_I18N_GEN_PATH,
   MODULE_INIT_SERVER_GEN_PATH,
-  MODULE_DATASTORES_GEN_PATH
+  MODULE_DATASTORES_GEN_PATH,
+  MODULE_SERVER_GEN_PATH
 ];
 function compareNames(a, b) {
   return a < b ? -1 : a > b ? 1 : 0;
@@ -4162,6 +4164,9 @@ function formatI18nMarker() {
 function formatInitMarker() {
   return `// ${MODULE_STUB_MARKER} scope=init`;
 }
+function formatServerMarker() {
+  return `// ${MODULE_STUB_MARKER} scope=server`;
+}
 function formatDatastoresMarker() {
   return `// ${MODULE_STUB_MARKER} scope=datastores`;
 }
@@ -4805,6 +4810,42 @@ function emitModuleInitServerGenTs(input) {
     ""
   ].join("\n");
 }
+function emitModuleServerGenTs(input) {
+  const installed = new Set(input.registry.modules.map((m) => m.name));
+  const moduleNames = input.facts.filter((f) => f.hasServerRegistrations && installed.has(f.moduleName)).map((f) => f.moduleName).sort(compareNames);
+  for (const name of moduleNames) {
+    if (!isValidModuleName(name)) {
+      throw new Error(`[ModuleRail] composition artifacts: invalid module name "${name}"`);
+    }
+  }
+  const importLines = moduleNames.map(
+    (name, index) => [
+      `@/modules/${name}/server/registrations`,
+      `import * as serverRegistrations${index} from ${JSON.stringify(`@/modules/${name}/server/registrations`)};`
+    ]
+  ).sort((a, b) => compareImportSpecifiers(a[0], b[0])).map(([, line]) => line);
+  const entryLines = moduleNames.map(
+    (name, index) => `  { module: ${JSON.stringify(name)}, registrations: serverRegistrations${index} },`
+  );
+  return [
+    formatServerMarker(),
+    "/** DO NOT EDIT \u2014 owned by the module install rail. */",
+    "",
+    ...importLines,
+    ...importLines.length > 0 ? [""] : [],
+    "export type ModuleServerRegistration = {",
+    "  module: string;",
+    "  registrations: Readonly<Record<string, unknown>>;",
+    "};",
+    "",
+    ...entryLines.length === 0 ? ["export const MODULE_SERVER_REGISTRATIONS: readonly ModuleServerRegistration[] = [];"] : [
+      "export const MODULE_SERVER_REGISTRATIONS: readonly ModuleServerRegistration[] = [",
+      ...entryLines,
+      "];"
+    ],
+    ""
+  ].join("\n");
+}
 
 // ../../packages/lib/src/server/module-rail/composition-artifacts.ts
 var COMPOSITION_ARTIFACTS_GENERATED_BY = "module-rail";
@@ -4867,6 +4908,14 @@ function formatRouteMarker(owner, nextRelativePath) {
 function formatRegistryMarker() {
   return `// ${MODULE_STUB_MARKER} scope=registry`;
 }
+var OWNERLESS_MARKER_KINDS = [
+  "registry",
+  "contributions",
+  "datastores",
+  "i18n",
+  "init",
+  "server"
+];
 function parseCompositionArtifactMarker(source) {
   const firstLine = source.split(/\r?\n/, 1)[0]?.trim() ?? "";
   const match = firstLine.match(
@@ -4877,26 +4926,8 @@ function parseCompositionArtifactMarker(source) {
   if (!match) return null;
   const owner = match[1];
   const scope = match[2];
-  if (scope === "registry") {
-    if (owner) return null;
-    return { kind: "registry" };
-  }
-  if (scope === "contributions") {
-    if (owner) return null;
-    return { kind: "contributions" };
-  }
-  if (scope === "datastores") {
-    if (owner) return null;
-    return { kind: "datastores" };
-  }
-  if (scope === "i18n") {
-    if (owner) return null;
-    return { kind: "i18n" };
-  }
-  if (scope === "init") {
-    if (owner) return null;
-    return { kind: "init" };
-  }
+  const ownerless = OWNERLESS_MARKER_KINDS.find((kind) => kind === scope);
+  if (ownerless) return owner ? null : { kind: ownerless };
   if (!owner || !isValidModuleName(owner)) return null;
   if (scope === "route") {
     const nextRelativePath = match[3]?.trim();
@@ -5022,6 +5053,7 @@ function expectedMarkerKindForPath(path3) {
   if (path3 === MODULE_DATASTORES_GEN_PATH) return "datastores";
   if (path3 === MODULE_I18N_GEN_PATH) return "i18n";
   if (path3 === MODULE_INIT_SERVER_GEN_PATH) return "init";
+  if (path3 === MODULE_SERVER_GEN_PATH) return "server";
   if (path3.startsWith(API_ROUTE_DIR_PREFIX) && path3.endsWith("/route.ts")) return "endpoint";
   if (path3.startsWith(APP_DIR_PREFIX) && !path3.startsWith(API_ROUTE_DIR_PREFIX) && PAGE_FILE_SUFFIXES.some((suffix) => path3.endsWith(suffix))) {
     return "route";
@@ -5621,6 +5653,7 @@ function planCompositionArtifacts(input) {
   let datastoresContent;
   let i18nContent;
   let initContent;
+  let serverContent;
   try {
     contributionsContent = emitModuleContributionsGenTs({
       registry: input.registry,
@@ -5645,6 +5678,10 @@ function planCompositionArtifacts(input) {
       registry: input.registry,
       facts: compositionEntryFacts
     });
+    serverContent = emitModuleServerGenTs({
+      registry: input.registry,
+      facts: compositionEntryFacts
+    });
   } catch (error) {
     return {
       ok: false,
@@ -5657,6 +5694,7 @@ function planCompositionArtifacts(input) {
   desired.set(MODULE_DATASTORES_GEN_PATH, datastoresContent);
   desired.set(MODULE_I18N_GEN_PATH, i18nContent);
   desired.set(MODULE_INIT_SERVER_GEN_PATH, initContent);
+  desired.set(MODULE_SERVER_GEN_PATH, serverContent);
   for (const stub of stubs.endpointStubs) desired.set(stub.path, stub.content);
   for (const stub of stubs.routeStubs) desired.set(stub.path, stub.content);
   const endpointStubByPath = new Map(stubs.endpointStubs.map((stub) => [stub.path, stub]));
@@ -6927,6 +6965,7 @@ function readFailurePath(error) {
   return typeof error === "object" && error !== null && "path" in error ? String(error.path) : "unknown";
 }
 var CONVENTIONAL_ENTRY_KIND_PROBE_TOKEN = "conventional-entry-kind";
+var SERVER_REGISTRATIONS_FILE = "server/registrations.ts";
 var COMPOSITION_ARTIFACT_KIND_PROBE_TOKEN = "composition-artifact-kind";
 async function classifyCompositionArtifactPathKind(context, path3) {
   return classifySandboxPathPresenceKind(context, path3, COMPOSITION_ARTIFACT_KIND_PROBE_TOKEN);
@@ -6964,6 +7003,10 @@ async function readConventionalEntryIfRealFile(path3, kind, presences, files) {
   }
   return source;
 }
+function hasRealServerRegistrations(modulePath, presences) {
+  const path3 = `${modulePath}/${SERVER_REGISTRATIONS_FILE}`;
+  return assertRealCompositionArtifactFilePresence(path3, presences.get(path3) ?? "unreadable") === "file";
+}
 async function readJsonObjectFile(path3, files) {
   const raw = files.get(path3);
   let parsed;
@@ -6987,6 +7030,9 @@ async function collectCompositionEntryFacts(context, registry) {
   const overridesDir = `${APP_PACKAGE_DIR}/src/lib/i18n/overrides`;
   const localeDirs = [substrateDir, overridesDir];
   const conventionalPaths = [];
+  const serverRegistrationPaths = registry.modules.map(
+    (mod) => `${MODULES_SANDBOX_DIR}/${mod.name}/${SERVER_REGISTRATIONS_FILE}`
+  );
   for (const mod of registry.modules) {
     const modulePath = `${MODULES_SANDBOX_DIR}/${mod.name}`;
     localeDirs.push(`${modulePath}/i18n`);
@@ -7015,7 +7061,7 @@ async function collectCompositionEntryFacts(context, registry) {
   const [conventionalPresences, localePresences] = await Promise.all([
     classifySandboxPathPresenceKindMany(
       context,
-      conventionalPaths,
+      [...conventionalPaths, ...serverRegistrationPaths],
       CONVENTIONAL_ENTRY_KIND_PROBE_TOKEN
     ),
     classifySandboxPathPresenceKindMany(context, localePaths, LOCALE_JSON_KIND_PROBE_TOKEN)
@@ -7077,6 +7123,7 @@ async function collectCompositionEntryFacts(context, registry) {
         );
       }
     }
+    const hasServerRegistrations = hasRealServerRegistrations(modulePath, conventionalPresences);
     const rootLocales = localesByDir.get(`${modulePath}/i18n`);
     if (rootLocales.length > 0 && !rootLocales.includes("en")) {
       throw new Error(
@@ -7116,6 +7163,7 @@ async function collectCompositionEntryFacts(context, registry) {
       moduleName: mod.name,
       hasRootContributions,
       hasRootSlots,
+      hasServerRegistrations,
       rootLocales,
       enhancements
     });
@@ -7319,6 +7367,7 @@ async function reconcileCompositionArtifacts(context, options = {}) {
     MODULE_DATASTORES_GEN_PATH,
     MODULE_I18N_GEN_PATH,
     MODULE_INIT_SERVER_GEN_PATH,
+    MODULE_SERVER_GEN_PATH,
     ...existingGeneratedPaths,
     ...Object.keys(existingAppPages),
     ...Object.keys(existingAppRoutes)

package/dist/index.d.mts

@@ -89,7 +89,7 @@ declare function assertSupportedTypescript(versionMajorMinor: string): void;
  */
 declare function escapeGitignore(pattern: string): string;
 /**
- * Regenerate the Module-rail artifacts (the five `src/*.gen.ts` files and every
+ * Regenerate the Module-rail artifacts (the six `src/*.gen.ts` files and every
  * route/endpoint stub under `src/app`) for the app rooted at `options.cwd`.
  */
 declare function compose(options: ComposeOptions): Promise<ComposeResult>;

package/dist/index.d.ts

@@ -89,7 +89,7 @@ declare function assertSupportedTypescript(versionMajorMinor: string): void;
  */
 declare function escapeGitignore(pattern: string): string;
 /**
- * Regenerate the Module-rail artifacts (the five `src/*.gen.ts` files and every
+ * Regenerate the Module-rail artifacts (the six `src/*.gen.ts` files and every
  * route/endpoint stub under `src/app`) for the app rooted at `options.cwd`.
  */
 declare function compose(options: ComposeOptions): Promise<ComposeResult>;

package/dist/index.js

@@ -4134,6 +4134,7 @@ var MODULE_CONTRIBUTIONS_GEN_PATH = `${APP_WEB_PREFIX}src/module-contributions.g
 var MODULE_DATASTORES_GEN_PATH = `${APP_WEB_PREFIX}src/module-datastores.gen.ts`;
 var MODULE_I18N_GEN_PATH = `${APP_WEB_PREFIX}src/module-i18n.gen.ts`;
 var MODULE_INIT_SERVER_GEN_PATH = `${APP_WEB_PREFIX}src/module-init.server.gen.ts`;
+var MODULE_SERVER_GEN_PATH = `${APP_WEB_PREFIX}src/module-server.gen.ts`;
 var MODULES_GEN_PATH = `${APP_WEB_PREFIX}src/modules.gen.ts`;
 var APP_EXTENSIONS_PATH = `${APP_WEB_PREFIX}src/lib/modules/app-extensions.ts`;
 
@@ -4150,7 +4151,8 @@ var COMPOSITION_RUNTIME_GEN_PATHS = [
   MODULE_CONTRIBUTIONS_GEN_PATH,
   MODULE_I18N_GEN_PATH,
   MODULE_INIT_SERVER_GEN_PATH,
-  MODULE_DATASTORES_GEN_PATH
+  MODULE_DATASTORES_GEN_PATH,
+  MODULE_SERVER_GEN_PATH
 ];
 function compareNames(a, b) {
   return a < b ? -1 : a > b ? 1 : 0;
@@ -4171,6 +4173,9 @@ function formatI18nMarker() {
 function formatInitMarker() {
   return `// ${MODULE_STUB_MARKER} scope=init`;
 }
+function formatServerMarker() {
+  return `// ${MODULE_STUB_MARKER} scope=server`;
+}
 function formatDatastoresMarker() {
   return `// ${MODULE_STUB_MARKER} scope=datastores`;
 }
@@ -4814,6 +4819,42 @@ function emitModuleInitServerGenTs(input) {
     ""
   ].join("\n");
 }
+function emitModuleServerGenTs(input) {
+  const installed = new Set(input.registry.modules.map((m) => m.name));
+  const moduleNames = input.facts.filter((f) => f.hasServerRegistrations && installed.has(f.moduleName)).map((f) => f.moduleName).sort(compareNames);
+  for (const name of moduleNames) {
+    if (!isValidModuleName(name)) {
+      throw new Error(`[ModuleRail] composition artifacts: invalid module name "${name}"`);
+    }
+  }
+  const importLines = moduleNames.map(
+    (name, index) => [
+      `@/modules/${name}/server/registrations`,
+      `import * as serverRegistrations${index} from ${JSON.stringify(`@/modules/${name}/server/registrations`)};`
+    ]
+  ).sort((a, b) => compareImportSpecifiers(a[0], b[0])).map(([, line]) => line);
+  const entryLines = moduleNames.map(
+    (name, index) => `  { module: ${JSON.stringify(name)}, registrations: serverRegistrations${index} },`
+  );
+  return [
+    formatServerMarker(),
+    "/** DO NOT EDIT \u2014 owned by the module install rail. */",
+    "",
+    ...importLines,
+    ...importLines.length > 0 ? [""] : [],
+    "export type ModuleServerRegistration = {",
+    "  module: string;",
+    "  registrations: Readonly<Record<string, unknown>>;",
+    "};",
+    "",
+    ...entryLines.length === 0 ? ["export const MODULE_SERVER_REGISTRATIONS: readonly ModuleServerRegistration[] = [];"] : [
+      "export const MODULE_SERVER_REGISTRATIONS: readonly ModuleServerRegistration[] = [",
+      ...entryLines,
+      "];"
+    ],
+    ""
+  ].join("\n");
+}
 
 // ../../packages/lib/src/server/module-rail/composition-artifacts.ts
 var COMPOSITION_ARTIFACTS_GENERATED_BY = "module-rail";
@@ -4876,6 +4917,14 @@ function formatRouteMarker(owner, nextRelativePath) {
 function formatRegistryMarker() {
   return `// ${MODULE_STUB_MARKER} scope=registry`;
 }
+var OWNERLESS_MARKER_KINDS = [
+  "registry",
+  "contributions",
+  "datastores",
+  "i18n",
+  "init",
+  "server"
+];
 function parseCompositionArtifactMarker(source) {
   const firstLine = source.split(/\r?\n/, 1)[0]?.trim() ?? "";
   const match = firstLine.match(
@@ -4886,26 +4935,8 @@ function parseCompositionArtifactMarker(source) {
   if (!match) return null;
   const owner = match[1];
   const scope = match[2];
-  if (scope === "registry") {
-    if (owner) return null;
-    return { kind: "registry" };
-  }
-  if (scope === "contributions") {
-    if (owner) return null;
-    return { kind: "contributions" };
-  }
-  if (scope === "datastores") {
-    if (owner) return null;
-    return { kind: "datastores" };
-  }
-  if (scope === "i18n") {
-    if (owner) return null;
-    return { kind: "i18n" };
-  }
-  if (scope === "init") {
-    if (owner) return null;
-    return { kind: "init" };
-  }
+  const ownerless = OWNERLESS_MARKER_KINDS.find((kind) => kind === scope);
+  if (ownerless) return owner ? null : { kind: ownerless };
   if (!owner || !isValidModuleName(owner)) return null;
   if (scope === "route") {
     const nextRelativePath = match[3]?.trim();
@@ -5031,6 +5062,7 @@ function expectedMarkerKindForPath(path3) {
   if (path3 === MODULE_DATASTORES_GEN_PATH) return "datastores";
   if (path3 === MODULE_I18N_GEN_PATH) return "i18n";
   if (path3 === MODULE_INIT_SERVER_GEN_PATH) return "init";
+  if (path3 === MODULE_SERVER_GEN_PATH) return "server";
   if (path3.startsWith(API_ROUTE_DIR_PREFIX) && path3.endsWith("/route.ts")) return "endpoint";
   if (path3.startsWith(APP_DIR_PREFIX) && !path3.startsWith(API_ROUTE_DIR_PREFIX) && PAGE_FILE_SUFFIXES.some((suffix) => path3.endsWith(suffix))) {
     return "route";
@@ -5630,6 +5662,7 @@ function planCompositionArtifacts(input) {
   let datastoresContent;
   let i18nContent;
   let initContent;
+  let serverContent;
   try {
     contributionsContent = emitModuleContributionsGenTs({
       registry: input.registry,
@@ -5654,6 +5687,10 @@ function planCompositionArtifacts(input) {
       registry: input.registry,
       facts: compositionEntryFacts
     });
+    serverContent = emitModuleServerGenTs({
+      registry: input.registry,
+      facts: compositionEntryFacts
+    });
   } catch (error) {
     return {
       ok: false,
@@ -5666,6 +5703,7 @@ function planCompositionArtifacts(input) {
   desired.set(MODULE_DATASTORES_GEN_PATH, datastoresContent);
   desired.set(MODULE_I18N_GEN_PATH, i18nContent);
   desired.set(MODULE_INIT_SERVER_GEN_PATH, initContent);
+  desired.set(MODULE_SERVER_GEN_PATH, serverContent);
   for (const stub of stubs.endpointStubs) desired.set(stub.path, stub.content);
   for (const stub of stubs.routeStubs) desired.set(stub.path, stub.content);
   const endpointStubByPath = new Map(stubs.endpointStubs.map((stub) => [stub.path, stub]));
@@ -6936,6 +6974,7 @@ function readFailurePath(error) {
   return typeof error === "object" && error !== null && "path" in error ? String(error.path) : "unknown";
 }
 var CONVENTIONAL_ENTRY_KIND_PROBE_TOKEN = "conventional-entry-kind";
+var SERVER_REGISTRATIONS_FILE = "server/registrations.ts";
 var COMPOSITION_ARTIFACT_KIND_PROBE_TOKEN = "composition-artifact-kind";
 async function classifyCompositionArtifactPathKind(context, path3) {
   return classifySandboxPathPresenceKind(context, path3, COMPOSITION_ARTIFACT_KIND_PROBE_TOKEN);
@@ -6973,6 +7012,10 @@ async function readConventionalEntryIfRealFile(path3, kind, presences, files) {
   }
   return source;
 }
+function hasRealServerRegistrations(modulePath, presences) {
+  const path3 = `${modulePath}/${SERVER_REGISTRATIONS_FILE}`;
+  return assertRealCompositionArtifactFilePresence(path3, presences.get(path3) ?? "unreadable") === "file";
+}
 async function readJsonObjectFile(path3, files) {
   const raw = files.get(path3);
   let parsed;
@@ -6996,6 +7039,9 @@ async function collectCompositionEntryFacts(context, registry) {
   const overridesDir = `${APP_PACKAGE_DIR}/src/lib/i18n/overrides`;
   const localeDirs = [substrateDir, overridesDir];
   const conventionalPaths = [];
+  const serverRegistrationPaths = registry.modules.map(
+    (mod) => `${MODULES_SANDBOX_DIR}/${mod.name}/${SERVER_REGISTRATIONS_FILE}`
+  );
   for (const mod of registry.modules) {
     const modulePath = `${MODULES_SANDBOX_DIR}/${mod.name}`;
     localeDirs.push(`${modulePath}/i18n`);
@@ -7024,7 +7070,7 @@ async function collectCompositionEntryFacts(context, registry) {
   const [conventionalPresences, localePresences] = await Promise.all([
     classifySandboxPathPresenceKindMany(
       context,
-      conventionalPaths,
+      [...conventionalPaths, ...serverRegistrationPaths],
       CONVENTIONAL_ENTRY_KIND_PROBE_TOKEN
     ),
     classifySandboxPathPresenceKindMany(context, localePaths, LOCALE_JSON_KIND_PROBE_TOKEN)
@@ -7086,6 +7132,7 @@ async function collectCompositionEntryFacts(context, registry) {
         );
       }
     }
+    const hasServerRegistrations = hasRealServerRegistrations(modulePath, conventionalPresences);
     const rootLocales = localesByDir.get(`${modulePath}/i18n`);
     if (rootLocales.length > 0 && !rootLocales.includes("en")) {
       throw new Error(
@@ -7125,6 +7172,7 @@ async function collectCompositionEntryFacts(context, registry) {
       moduleName: mod.name,
       hasRootContributions,
       hasRootSlots,
+      hasServerRegistrations,
       rootLocales,
       enhancements
     });
@@ -7328,6 +7376,7 @@ async function reconcileCompositionArtifacts(context, options = {}) {
     MODULE_DATASTORES_GEN_PATH,
     MODULE_I18N_GEN_PATH,
     MODULE_INIT_SERVER_GEN_PATH,
+    MODULE_SERVER_GEN_PATH,
     ...existingGeneratedPaths,
     ...Object.keys(existingAppPages),
     ...Object.keys(existingAppRoutes)

package/dist/index.mjs

@@ -4119,6 +4119,7 @@ var MODULE_CONTRIBUTIONS_GEN_PATH = `${APP_WEB_PREFIX}src/module-contributions.g
 var MODULE_DATASTORES_GEN_PATH = `${APP_WEB_PREFIX}src/module-datastores.gen.ts`;
 var MODULE_I18N_GEN_PATH = `${APP_WEB_PREFIX}src/module-i18n.gen.ts`;
 var MODULE_INIT_SERVER_GEN_PATH = `${APP_WEB_PREFIX}src/module-init.server.gen.ts`;
+var MODULE_SERVER_GEN_PATH = `${APP_WEB_PREFIX}src/module-server.gen.ts`;
 var MODULES_GEN_PATH = `${APP_WEB_PREFIX}src/modules.gen.ts`;
 var APP_EXTENSIONS_PATH = `${APP_WEB_PREFIX}src/lib/modules/app-extensions.ts`;
 
@@ -4135,7 +4136,8 @@ var COMPOSITION_RUNTIME_GEN_PATHS = [
   MODULE_CONTRIBUTIONS_GEN_PATH,
   MODULE_I18N_GEN_PATH,
   MODULE_INIT_SERVER_GEN_PATH,
-  MODULE_DATASTORES_GEN_PATH
+  MODULE_DATASTORES_GEN_PATH,
+  MODULE_SERVER_GEN_PATH
 ];
 function compareNames(a, b) {
   return a < b ? -1 : a > b ? 1 : 0;
@@ -4156,6 +4158,9 @@ function formatI18nMarker() {
 function formatInitMarker() {
   return `// ${MODULE_STUB_MARKER} scope=init`;
 }
+function formatServerMarker() {
+  return `// ${MODULE_STUB_MARKER} scope=server`;
+}
 function formatDatastoresMarker() {
   return `// ${MODULE_STUB_MARKER} scope=datastores`;
 }
@@ -4799,6 +4804,42 @@ function emitModuleInitServerGenTs(input) {
     ""
   ].join("\n");
 }
+function emitModuleServerGenTs(input) {
+  const installed = new Set(input.registry.modules.map((m) => m.name));
+  const moduleNames = input.facts.filter((f) => f.hasServerRegistrations && installed.has(f.moduleName)).map((f) => f.moduleName).sort(compareNames);
+  for (const name of moduleNames) {
+    if (!isValidModuleName(name)) {
+      throw new Error(`[ModuleRail] composition artifacts: invalid module name "${name}"`);
+    }
+  }
+  const importLines = moduleNames.map(
+    (name, index) => [
+      `@/modules/${name}/server/registrations`,
+      `import * as serverRegistrations${index} from ${JSON.stringify(`@/modules/${name}/server/registrations`)};`
+    ]
+  ).sort((a, b) => compareImportSpecifiers(a[0], b[0])).map(([, line]) => line);
+  const entryLines = moduleNames.map(
+    (name, index) => `  { module: ${JSON.stringify(name)}, registrations: serverRegistrations${index} },`
+  );
+  return [
+    formatServerMarker(),
+    "/** DO NOT EDIT \u2014 owned by the module install rail. */",
+    "",
+    ...importLines,
+    ...importLines.length > 0 ? [""] : [],
+    "export type ModuleServerRegistration = {",
+    "  module: string;",
+    "  registrations: Readonly<Record<string, unknown>>;",
+    "};",
+    "",
+    ...entryLines.length === 0 ? ["export const MODULE_SERVER_REGISTRATIONS: readonly ModuleServerRegistration[] = [];"] : [
+      "export const MODULE_SERVER_REGISTRATIONS: readonly ModuleServerRegistration[] = [",
+      ...entryLines,
+      "];"
+    ],
+    ""
+  ].join("\n");
+}
 
 // ../../packages/lib/src/server/module-rail/composition-artifacts.ts
 var COMPOSITION_ARTIFACTS_GENERATED_BY = "module-rail";
@@ -4861,6 +4902,14 @@ function formatRouteMarker(owner, nextRelativePath) {
 function formatRegistryMarker() {
   return `// ${MODULE_STUB_MARKER} scope=registry`;
 }
+var OWNERLESS_MARKER_KINDS = [
+  "registry",
+  "contributions",
+  "datastores",
+  "i18n",
+  "init",
+  "server"
+];
 function parseCompositionArtifactMarker(source) {
   const firstLine = source.split(/\r?\n/, 1)[0]?.trim() ?? "";
   const match = firstLine.match(
@@ -4871,26 +4920,8 @@ function parseCompositionArtifactMarker(source) {
   if (!match) return null;
   const owner = match[1];
   const scope = match[2];
-  if (scope === "registry") {
-    if (owner) return null;
-    return { kind: "registry" };
-  }
-  if (scope === "contributions") {
-    if (owner) return null;
-    return { kind: "contributions" };
-  }
-  if (scope === "datastores") {
-    if (owner) return null;
-    return { kind: "datastores" };
-  }
-  if (scope === "i18n") {
-    if (owner) return null;
-    return { kind: "i18n" };
-  }
-  if (scope === "init") {
-    if (owner) return null;
-    return { kind: "init" };
-  }
+  const ownerless = OWNERLESS_MARKER_KINDS.find((kind) => kind === scope);
+  if (ownerless) return owner ? null : { kind: ownerless };
   if (!owner || !isValidModuleName(owner)) return null;
   if (scope === "route") {
     const nextRelativePath = match[3]?.trim();
@@ -5016,6 +5047,7 @@ function expectedMarkerKindForPath(path3) {
   if (path3 === MODULE_DATASTORES_GEN_PATH) return "datastores";
   if (path3 === MODULE_I18N_GEN_PATH) return "i18n";
   if (path3 === MODULE_INIT_SERVER_GEN_PATH) return "init";
+  if (path3 === MODULE_SERVER_GEN_PATH) return "server";
   if (path3.startsWith(API_ROUTE_DIR_PREFIX) && path3.endsWith("/route.ts")) return "endpoint";
   if (path3.startsWith(APP_DIR_PREFIX) && !path3.startsWith(API_ROUTE_DIR_PREFIX) && PAGE_FILE_SUFFIXES.some((suffix) => path3.endsWith(suffix))) {
     return "route";
@@ -5615,6 +5647,7 @@ function planCompositionArtifacts(input) {
   let datastoresContent;
   let i18nContent;
   let initContent;
+  let serverContent;
   try {
     contributionsContent = emitModuleContributionsGenTs({
       registry: input.registry,
@@ -5639,6 +5672,10 @@ function planCompositionArtifacts(input) {
       registry: input.registry,
       facts: compositionEntryFacts
     });
+    serverContent = emitModuleServerGenTs({
+      registry: input.registry,
+      facts: compositionEntryFacts
+    });
   } catch (error) {
     return {
       ok: false,
@@ -5651,6 +5688,7 @@ function planCompositionArtifacts(input) {
   desired.set(MODULE_DATASTORES_GEN_PATH, datastoresContent);
   desired.set(MODULE_I18N_GEN_PATH, i18nContent);
   desired.set(MODULE_INIT_SERVER_GEN_PATH, initContent);
+  desired.set(MODULE_SERVER_GEN_PATH, serverContent);
   for (const stub of stubs.endpointStubs) desired.set(stub.path, stub.content);
   for (const stub of stubs.routeStubs) desired.set(stub.path, stub.content);
   const endpointStubByPath = new Map(stubs.endpointStubs.map((stub) => [stub.path, stub]));
@@ -6921,6 +6959,7 @@ function readFailurePath(error) {
   return typeof error === "object" && error !== null && "path" in error ? String(error.path) : "unknown";
 }
 var CONVENTIONAL_ENTRY_KIND_PROBE_TOKEN = "conventional-entry-kind";
+var SERVER_REGISTRATIONS_FILE = "server/registrations.ts";
 var COMPOSITION_ARTIFACT_KIND_PROBE_TOKEN = "composition-artifact-kind";
 async function classifyCompositionArtifactPathKind(context, path3) {
   return classifySandboxPathPresenceKind(context, path3, COMPOSITION_ARTIFACT_KIND_PROBE_TOKEN);
@@ -6958,6 +6997,10 @@ async function readConventionalEntryIfRealFile(path3, kind, presences, files) {
   }
   return source;
 }
+function hasRealServerRegistrations(modulePath, presences) {
+  const path3 = `${modulePath}/${SERVER_REGISTRATIONS_FILE}`;
+  return assertRealCompositionArtifactFilePresence(path3, presences.get(path3) ?? "unreadable") === "file";
+}
 async function readJsonObjectFile(path3, files) {
   const raw = files.get(path3);
   let parsed;
@@ -6981,6 +7024,9 @@ async function collectCompositionEntryFacts(context, registry) {
   const overridesDir = `${APP_PACKAGE_DIR}/src/lib/i18n/overrides`;
   const localeDirs = [substrateDir, overridesDir];
   const conventionalPaths = [];
+  const serverRegistrationPaths = registry.modules.map(
+    (mod) => `${MODULES_SANDBOX_DIR}/${mod.name}/${SERVER_REGISTRATIONS_FILE}`
+  );
   for (const mod of registry.modules) {
     const modulePath = `${MODULES_SANDBOX_DIR}/${mod.name}`;
     localeDirs.push(`${modulePath}/i18n`);
@@ -7009,7 +7055,7 @@ async function collectCompositionEntryFacts(context, registry) {
   const [conventionalPresences, localePresences] = await Promise.all([
     classifySandboxPathPresenceKindMany(
       context,
-      conventionalPaths,
+      [...conventionalPaths, ...serverRegistrationPaths],
       CONVENTIONAL_ENTRY_KIND_PROBE_TOKEN
     ),
     classifySandboxPathPresenceKindMany(context, localePaths, LOCALE_JSON_KIND_PROBE_TOKEN)
@@ -7071,6 +7117,7 @@ async function collectCompositionEntryFacts(context, registry) {
         );
       }
     }
+    const hasServerRegistrations = hasRealServerRegistrations(modulePath, conventionalPresences);
     const rootLocales = localesByDir.get(`${modulePath}/i18n`);
     if (rootLocales.length > 0 && !rootLocales.includes("en")) {
       throw new Error(
@@ -7110,6 +7157,7 @@ async function collectCompositionEntryFacts(context, registry) {
       moduleName: mod.name,
       hasRootContributions,
       hasRootSlots,
+      hasServerRegistrations,
       rootLocales,
       enhancements
     });
@@ -7313,6 +7361,7 @@ async function reconcileCompositionArtifacts(context, options = {}) {
     MODULE_DATASTORES_GEN_PATH,
     MODULE_I18N_GEN_PATH,
     MODULE_INIT_SERVER_GEN_PATH,
+    MODULE_SERVER_GEN_PATH,
     ...existingGeneratedPaths,
     ...Object.keys(existingAppPages),
     ...Object.keys(existingAppRoutes)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stardeck-customer-apps/compose",
-  "version": "0.7.0",
-  "description": "Regenerates a Stardeck app's Module-rail artifacts — the five src/*.gen.ts registries and every route/endpoint stub — from src/modules/*/module.json",
+  "version": "0.8.0",
+  "description": "Regenerates a Stardeck app's Module-rail artifacts — the six src/*.gen.ts registries and every route/endpoint stub — from src/modules/*/module.json",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",