@stardeck-customer-apps/compose 0.12.0 → 0.14.0

package/SKILL.md

@@ -12,7 +12,9 @@ Compose turns that declaration into the code Next.js actually builds:
 - `apps/web/src/modules.gen.ts` — the Module registry, `isModuleEnabled` and `isMountHeadless`
 - `apps/web/src/module-contributions.gen.ts`
 - `apps/web/src/module-i18n.gen.ts`
-- `apps/web/src/module-init.server.gen.ts`
+- `apps/web/src/module-init.server.gen.ts` — memoized `initializeActiveEnhancements()`:
+  each enabled Module's root `initializeModule`, then each active slice's
+  `initializeEnhancement`
 - `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`
@@ -149,6 +151,38 @@ a silent fallback. It holds deployment facts: gitignore it (`apps/web/.gitignore
   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.
+- **Module initializers.** Server registrations a Module makes into shared
+  registries (observers, resolvers, facets, drains) go in a root
+  `initialize.server.ts`, any Module kind:
+
+  ```ts
+  // src/modules/guest-ordering/initialize.server.ts — server-only, idempotent
+  import { registerPosCloseObserver } from "@/modules/pos/server";
+
+  import { wakeReconcileForClosedOrder } from "./server/reconcile";
+
+  export async function initializeModule() {
+    registerPosCloseObserver(wakeReconcileForClosedOrder);
+  }
+  ```
+
+  `initializeModule` must be a direct named function declaration callable with
+  zero required arguments (no arrow function, default export, re-export or
+  generator); compose fails otherwise. Compose imports it into
+  `module-init.server.gen.ts`, guarded by `isModuleEnabled("<module>")`, and
+  runs every Module initializer before any enhancement initializer, once per
+  instance. Every generated page stub (its render and its `generateMetadata`)
+  and every generated API route stub awaits `initializeActiveEnhancements()`
+  before its enablement guards, so the registrations exist in the route's own
+  module graph. Page stubs await it from compose 0.14.0; before that only API
+  stubs did. An `initialize()` export
+  run only from `instrumentation.ts` does not give you that: Next.js loads
+  instrumentation in a separate module graph, so on a cold instance the route
+  handlers and server components never see what it registered. A Module left
+  out by `--enabled` is not imported. Needs compose 0.14.0 or later (and
+  `@stardeck-customer-apps/eslint-plugin` 1.8.0 or later, whose
+  `no-module-internal-import` lets the generated file import it).
+
 - `@stardeck-customer-apps/compose/runtime` exports `isModuleEnabledByList`,
   the single enablement rule, and imports nothing — it is safe in client
   components.

package/dist/cli.js

@@ -2249,14 +2249,22 @@ var datastoreRequirementSchema = import_zod.z.object({
   /** Checked against the connected store's accessLevel at install. */
   access: import_zod.z.enum(["read", "write", "admin"]).default("write")
 }).strict();
-var permissionClaimSchema = import_zod.z.object({
+var MODULE_PERMISSION_DEFAULT_ROLES = ["manager", "member", "viewer"];
+var modulePermissionClaimSchema = import_zod.z.object({
   /**
    * Lowercase resource:action with one colon and no underscores. This grammar
    * is deliberately narrower than the platform permission tool's charset.
    */
   key: import_zod.z.string().regex(/^[a-z0-9][a-z0-9-]*:[a-z0-9][a-z0-9-]*$/, "must be a lowercase resource:action key").max(100, "must be at most 100 characters (platform permission tool limit)"),
   /** Human label for the deployment auth config row. */
-  description: descriptionSchema
+  description: descriptionSchema,
+  /**
+   * The default organization roles that hold this key when the platform
+   * first registers it on an app (a Blueprint fork, a Module install). Admin
+   * holds every key without being listed; External Viewer never holds one.
+   * Changing a role's grants afterwards is the organization's business.
+   */
+  roles: import_zod.z.array(import_zod.z.enum(MODULE_PERMISSION_DEFAULT_ROLES)).optional()
 }).strict();
 var seedBundleSchema = import_zod.z.object({
   table: tableNameSchema,
@@ -2339,7 +2347,7 @@ var moduleManifestSchema = import_zod.z.object({
    * Keys this module's guards enforce. Install registers them in deployment
    * auth config; registration only — declaring is never granting.
    */
-  permissions: import_zod.z.array(permissionClaimSchema).optional(),
+  permissions: import_zod.z.array(modulePermissionClaimSchema).optional(),
   /**
    * Optional starter rows for tables this module owns. Replay is
    * `INSERT ... ON CONFLICT (conflictTarget) DO NOTHING` — idempotent by
@@ -3552,17 +3560,20 @@ var import_typescript3 = __toESM(require("typescript"), 1);
 var CONVENTIONAL_ENTRY_EXPORT_NAME = {
   contributions: "contributions",
   slotCatalogs: "slotCatalogs",
-  initializeEnhancement: "initializeEnhancement"
+  initializeEnhancement: "initializeEnhancement",
+  initializeModule: "initializeModule"
 };
 var CONVENTIONAL_ENTRY_DECLARATION_KIND = {
   contributions: "variable",
   slotCatalogs: "variable",
-  initializeEnhancement: "function"
+  initializeEnhancement: "function",
+  initializeModule: "function"
 };
 var CONVENTIONAL_ENTRY_FILENAME = {
   contributions: "contributions.ts",
   slotCatalogs: "slots.ts",
-  initializeEnhancement: "initialize.server.ts"
+  initializeEnhancement: "initialize.server.ts",
+  initializeModule: "initialize.server.ts"
 };
 function hasModifierKind(modifiers, kind) {
   return Boolean(modifiers?.some((m) => m.kind === kind));
@@ -3661,7 +3672,7 @@ function analyzeConventionalEntryExportWithTs(typescript, sourceText, kind, file
         }
         if (!isZeroArgumentInvocable(typescript, stmt.parameters)) {
           errors.push(
-            `"${entryName}" must be invocable with zero arguments (generated caller uses initializeEnhancement()); required parameters are forbidden \u2014 use optional, default, rest, or a this-parameter only`
+            `"${entryName}" must be invocable with zero arguments (generated caller uses ${entryName}()); required parameters are forbidden \u2014 use optional, default, rest, or a this-parameter only`
           );
           continue;
         }
@@ -3961,11 +3972,18 @@ ${result.error}`);
 }
 
 // ../../packages/lib/src/server/sandbox/redact-secrets.ts
+var SECRET_NAME = String.raw`[A-Z][A-Z0-9_]*(?:_SECRET|_SECRET_KEY|_API_KEY|_KEY|_TOKEN|_PASSWORD)`;
+var SECRET_ASSIGNMENT = new RegExp(
+  String.raw`\b(${SECRET_NAME})\s*=\s*(?:'(?:[^']|'\\'')*'|"[^"]*"|[^\s&"',;}\]]+)`,
+  "g"
+);
+var JSON_SECRET_PAIR = new RegExp(
+  String.raw`"(${SECRET_NAME})"(\s*:\s*)"(?:[^"\\\n]|\\.)*"`,
+  "g"
+);
+var SECRET_QUOTE_OPENER = new RegExp(String.raw`\b${SECRET_NAME}\s*=\s*(['"])`, "g");
 function redactSecrets(text) {
-  return text.replace(/x-access-token:[^@\s]+@/g, "x-access-token:***@").replace(/https:\/\/(?!x-access-token:)[^/\s:@]+:[^/\s@]+@/gi, "https://***:***@").replace(/\b(gh[pousr]_)[A-Za-z0-9]+/g, "$1***").replace(/\b(github_pat_)[A-Za-z0-9_]+/g, "$1***").replace(/\b(postgres(?:ql)?:\/\/)([^:\s/@]+):([^@\s/]+)@/gi, "$1$2:***@").replace(/\b(npm_[A-Za-z0-9]+)/g, "npm_***").replace(/(_authToken=)([^\s&]+)/gi, "$1***").replace(
-    /\b([A-Z][A-Z0-9_]*(?:_SECRET|_SECRET_KEY|_API_KEY|_KEY|_TOKEN|_PASSWORD))\s*=\s*(?:'(?:[^']|'\\'')*'|"[^"]*"|[^\s&"',;}\]]+)/g,
-    "$1=***"
-  ).replace(/\b(Authorization:\s*(?:Bearer|Basic)\s+)\S+/gi, "$1***");
+  return text.replace(/x-access-token:[^@\s]+@/g, "x-access-token:***@").replace(/https:\/\/(?!x-access-token:)[^/\s:@]+:[^/\s@]+@/gi, "https://***:***@").replace(/\b(gh[pousr]_)[A-Za-z0-9]+/g, "$1***").replace(/\b(github_pat_)[A-Za-z0-9_]+/g, "$1***").replace(/\b(postgres(?:ql)?:\/\/)([^:\s/@]+):([^@\s/]+)@/gi, "$1$2:***@").replace(/\b(npm_[A-Za-z0-9]+)/g, "npm_***").replace(/(_authToken=)([^\s&]+)/gi, "$1***").replace(SECRET_ASSIGNMENT, "$1=***").replace(JSON_SECRET_PAIR, '"$1"$2"***"').replace(/\b(Authorization:\s*(?:Bearer|Basic)\s+)\S+/gi, "$1***");
 }
 
 // ../../packages/lib/src/server/sandbox/sh-quote.ts
@@ -4135,6 +4153,9 @@ function assertSlotCatalogsExport(source, pathLabel) {
 function assertInitializeEnhancementExport(source, pathLabel) {
   assertConventionalEntryExport(source, pathLabel, "initializeEnhancement");
 }
+function assertInitializeModuleExport(source, pathLabel) {
+  assertConventionalEntryExport(source, pathLabel, "initializeModule");
+}
 function assertClientSafeConventionalEntryImports(source, pathLabel, kind) {
   const { analysisErrors } = analyzeClientSafeEntryImports(
     source,
@@ -4654,30 +4675,47 @@ function deriveModuleLocaleLayers(registry, facts) {
   }
   return layers;
 }
-function emitModuleInitServerGenTs(input) {
+function moduleInitializerCalls(registry, facts) {
+  const installed = new Set(registry.modules.map((m) => m.name));
+  return facts.filter((f) => f.hasRootInitializeServer && installed.has(f.moduleName)).map((f) => f.moduleName).sort(compareNames).map((name, index) => {
+    if (!isValidModuleName(name)) {
+      throw new Error(`[ModuleRail] composition artifacts: invalid module name "${name}"`);
+    }
+    return {
+      exportName: "initializeModule",
+      guard: [name],
+      ident: `initializeModule${index}`,
+      importPath: `@/modules/${name}/initialize.server`
+    };
+  });
+}
+function enhancementInitializerCalls(registry, facts) {
   const calls = [];
-  const installed = new Set(input.registry.modules.map((m) => m.name));
-  let initializerIndex = 0;
-  for (const facts of [...input.facts].sort((a, b) => compareNames(a.moduleName, b.moduleName))) {
-    if (!installed.has(facts.moduleName)) continue;
-    const peers = activePeers(input.registry, facts.moduleName);
-    for (const enh of [...facts.enhancements].sort((a, b) => compareNames(a.peer, b.peer))) {
+  const installed = new Set(registry.modules.map((m) => m.name));
+  for (const f of [...facts].sort((a, b) => compareNames(a.moduleName, b.moduleName))) {
+    if (!installed.has(f.moduleName)) continue;
+    const peers = activePeers(registry, f.moduleName);
+    for (const enh of [...f.enhancements].sort((a, b) => compareNames(a.peer, b.peer))) {
       if (!enh.active || !peers.has(enh.peer)) continue;
       if (!enh.hasInitializeServer) continue;
-      const ident = `initializeEnhancement${initializerIndex++}`;
       calls.push({
-        owner: facts.moduleName,
-        peer: enh.peer,
-        ident,
-        importPath: `@/modules/${facts.moduleName}/enhancements/${enh.peer}/initialize.server`
+        exportName: "initializeEnhancement",
+        guard: [f.moduleName, enh.peer],
+        ident: `initializeEnhancement${calls.length}`,
+        importPath: `@/modules/${f.moduleName}/enhancements/${enh.peer}/initialize.server`
       });
     }
   }
-  const importLines = calls.map(
-    (c) => `import { initializeEnhancement as ${c.ident} } from ${JSON.stringify(c.importPath)};`
-  );
+  return calls;
+}
+function emitModuleInitServerGenTs(input) {
+  const moduleCalls = moduleInitializerCalls(input.registry, input.facts);
+  const enhancementCalls = enhancementInitializerCalls(input.registry, input.facts);
+  const calls = [...moduleCalls, ...enhancementCalls];
+  const importFor = (c) => `import { ${c.exportName} as ${c.ident} } from ${JSON.stringify(c.importPath)};`;
+  const importLines = moduleCalls.length === 0 ? calls.map(importFor) : [...calls].sort((a, b) => compareImportSpecifiers(a.importPath, b.importPath)).map(importFor);
   const callLines = calls.length === 0 ? ["      // Empty composition \u2014 no active enhancement initializers."] : calls.map(
-    (c) => `      if (enabled(${JSON.stringify(c.owner)}) && enabled(${JSON.stringify(c.peer)})) await ${c.ident}();`
+    (c) => `      if (${c.guard.map((name) => `enabled(${JSON.stringify(name)})`).join(" && ")}) await ${c.ident}();`
   );
   return [
     formatInitMarker(),
@@ -5127,6 +5165,7 @@ function buildRouteStubContent(input) {
     'import { notFound } from "next/navigation";',
     // simple-import-sort puts packages and "@/" aliases in separate groups.
     "",
+    'import { initializeActiveEnhancements } from "@/module-init.server.gen";',
     'import { isModuleEnabled, isMountHeadless } from "@/modules.gen";',
     `import Page from ${emitTsString(input.importModule)};`
   ];
@@ -5135,6 +5174,7 @@ function buildRouteStubContent(input) {
       `import { generateMetadata as sourceGenerateMetadata } from ${emitTsString(input.importModule)};`,
       "",
       "export async function generateMetadata(...args: Parameters<typeof sourceGenerateMetadata>) {",
+      "  await initializeActiveEnhancements();",
       ...emitGuardLines(guards, "return {};"),
       "  return sourceGenerateMetadata(...args);",
       "}"
@@ -5145,7 +5185,10 @@ function buildRouteStubContent(input) {
     "type PageProps =",
     "  Parameters<typeof Page> extends [infer P, ...unknown[]] ? NonNullable<P> : Record<never, never>;",
     "",
-    "export default function ModulePage(props: PageProps) {",
+    // Module and enhancement initializers run in this route's own module graph
+    // (memoized), so a cold server render sees their registrations.
+    "export default async function ModulePage(props: PageProps) {",
+    "  await initializeActiveEnhancements();",
     ...emitGuardLines(guards, "notFound();"),
     "  return <Page {...props} />;",
     "}",
@@ -5945,11 +5988,10 @@ var creationSourceBlueprintSchema = import_zod7.z.object({
    * `null`/absent means every feature Module: the platform stores that as the
    * explicit list of feature Modules in the published Blueprint version the fork
    * is cut from, so a Module a later Blueprint update adds arrives off. `[]` is
-   * refused: the platform serialises it to an empty
-   * `NEXT_PUBLIC_STARDECK_ENABLED_MODULES`, which the enablement parser reads
-   * back as "all" (`module-enablement.ts`) — the opposite of an empty selection.
+   * a custom app: no feature Module, Library Modules only (`resolvePlatformEnv`
+   * emits it as a set value naming no Module).
    */
-  enabledModules: import_zod7.z.array(moduleNameSchema).min(1, "Enable at least one Module").max(100).nullable().optional()
+  enabledModules: import_zod7.z.array(moduleNameSchema).max(100).nullable().optional()
 });
 var creationSourceSchema = import_zod7.z.discriminatedUnion("type", [
   creationSourceBlankSchema,
@@ -6944,6 +6986,9 @@ async function readConventionalEntryIfRealFile(path5, kind, presences, files) {
     case "initializeEnhancement":
       assertInitializeEnhancementExport(source, path5);
       break;
+    case "initializeModule":
+      assertInitializeModuleExport(source, path5);
+      break;
   }
   return source;
 }
@@ -6980,7 +7025,11 @@ async function collectCompositionEntryFacts(context, registry) {
   for (const mod of registry.modules) {
     const modulePath = `${MODULES_SANDBOX_DIR}/${mod.name}`;
     localeDirs.push(`${modulePath}/i18n`);
-    conventionalPaths.push(`${modulePath}/contributions.ts`, `${modulePath}/slots.ts`);
+    conventionalPaths.push(
+      `${modulePath}/contributions.ts`,
+      `${modulePath}/slots.ts`,
+      `${modulePath}/initialize.server.ts`
+    );
     for (const enh of mod.enhancements) {
       const peerDir = `${modulePath}/enhancements/${enh.peer}`;
       localeDirs.push(`${peerDir}/i18n`);
@@ -7068,6 +7117,17 @@ async function collectCompositionEntryFacts(context, registry) {
       }
     }
     const hasServerRegistrations = hasRealServerRegistrations(modulePath, conventionalPresences);
+    const hasRootInitializeServer = await readConventionalEntryIfRealFile(
+      `${modulePath}/initialize.server.ts`,
+      "initializeModule",
+      conventionalPresences,
+      files
+    ) != null;
+    if (hasRootInitializeServer) {
+      console.log(
+        `[ModuleRail] runId=${context.runId} module=${mod.name} has root initialize.server.ts (initializeModule)`
+      );
+    }
     const rootLocales = localesByDir.get(`${modulePath}/i18n`);
     if (rootLocales.length > 0 && !rootLocales.includes("en")) {
       throw new Error(
@@ -7108,6 +7168,7 @@ async function collectCompositionEntryFacts(context, registry) {
       hasRootContributions,
       hasRootSlots,
       hasServerRegistrations,
+      hasRootInitializeServer,
       rootLocales,
       enhancements
     });

package/dist/index.js

@@ -2087,11 +2087,18 @@ ${result.error}`);
 }
 
 // ../../packages/lib/src/server/sandbox/redact-secrets.ts
+var SECRET_NAME = String.raw`[A-Z][A-Z0-9_]*(?:_SECRET|_SECRET_KEY|_API_KEY|_KEY|_TOKEN|_PASSWORD)`;
+var SECRET_ASSIGNMENT = new RegExp(
+  String.raw`\b(${SECRET_NAME})\s*=\s*(?:'(?:[^']|'\\'')*'|"[^"]*"|[^\s&"',;}\]]+)`,
+  "g"
+);
+var JSON_SECRET_PAIR = new RegExp(
+  String.raw`"(${SECRET_NAME})"(\s*:\s*)"(?:[^"\\\n]|\\.)*"`,
+  "g"
+);
+var SECRET_QUOTE_OPENER = new RegExp(String.raw`\b${SECRET_NAME}\s*=\s*(['"])`, "g");
 function redactSecrets(text) {
-  return text.replace(/x-access-token:[^@\s]+@/g, "x-access-token:***@").replace(/https:\/\/(?!x-access-token:)[^/\s:@]+:[^/\s@]+@/gi, "https://***:***@").replace(/\b(gh[pousr]_)[A-Za-z0-9]+/g, "$1***").replace(/\b(github_pat_)[A-Za-z0-9_]+/g, "$1***").replace(/\b(postgres(?:ql)?:\/\/)([^:\s/@]+):([^@\s/]+)@/gi, "$1$2:***@").replace(/\b(npm_[A-Za-z0-9]+)/g, "npm_***").replace(/(_authToken=)([^\s&]+)/gi, "$1***").replace(
-    /\b([A-Z][A-Z0-9_]*(?:_SECRET|_SECRET_KEY|_API_KEY|_KEY|_TOKEN|_PASSWORD))\s*=\s*(?:'(?:[^']|'\\'')*'|"[^"]*"|[^\s&"',;}\]]+)/g,
-    "$1=***"
-  ).replace(/\b(Authorization:\s*(?:Bearer|Basic)\s+)\S+/gi, "$1***");
+  return text.replace(/x-access-token:[^@\s]+@/g, "x-access-token:***@").replace(/https:\/\/(?!x-access-token:)[^/\s:@]+:[^/\s@]+@/gi, "https://***:***@").replace(/\b(gh[pousr]_)[A-Za-z0-9]+/g, "$1***").replace(/\b(github_pat_)[A-Za-z0-9_]+/g, "$1***").replace(/\b(postgres(?:ql)?:\/\/)([^:\s/@]+):([^@\s/]+)@/gi, "$1$2:***@").replace(/\b(npm_[A-Za-z0-9]+)/g, "npm_***").replace(/(_authToken=)([^\s&]+)/gi, "$1***").replace(SECRET_ASSIGNMENT, "$1=***").replace(JSON_SECRET_PAIR, '"$1"$2"***"').replace(/\b(Authorization:\s*(?:Bearer|Basic)\s+)\S+/gi, "$1***");
 }
 
 // ../../packages/lib/src/server/sandbox/sh-quote.ts
@@ -2371,14 +2378,22 @@ var datastoreRequirementSchema = import_zod2.z.object({
   /** Checked against the connected store's accessLevel at install. */
   access: import_zod2.z.enum(["read", "write", "admin"]).default("write")
 }).strict();
-var permissionClaimSchema = import_zod2.z.object({
+var MODULE_PERMISSION_DEFAULT_ROLES = ["manager", "member", "viewer"];
+var modulePermissionClaimSchema = import_zod2.z.object({
   /**
    * Lowercase resource:action with one colon and no underscores. This grammar
    * is deliberately narrower than the platform permission tool's charset.
    */
   key: import_zod2.z.string().regex(/^[a-z0-9][a-z0-9-]*:[a-z0-9][a-z0-9-]*$/, "must be a lowercase resource:action key").max(100, "must be at most 100 characters (platform permission tool limit)"),
   /** Human label for the deployment auth config row. */
-  description: descriptionSchema
+  description: descriptionSchema,
+  /**
+   * The default organization roles that hold this key when the platform
+   * first registers it on an app (a Blueprint fork, a Module install). Admin
+   * holds every key without being listed; External Viewer never holds one.
+   * Changing a role's grants afterwards is the organization's business.
+   */
+  roles: import_zod2.z.array(import_zod2.z.enum(MODULE_PERMISSION_DEFAULT_ROLES)).optional()
 }).strict();
 var seedBundleSchema = import_zod2.z.object({
   table: tableNameSchema,
@@ -2461,7 +2476,7 @@ var moduleManifestSchema = import_zod2.z.object({
    * Keys this module's guards enforce. Install registers them in deployment
    * auth config; registration only — declaring is never granting.
    */
-  permissions: import_zod2.z.array(permissionClaimSchema).optional(),
+  permissions: import_zod2.z.array(modulePermissionClaimSchema).optional(),
   /**
    * Optional starter rows for tables this module owns. Replay is
    * `INSERT ... ON CONFLICT (conflictTarget) DO NOTHING` — idempotent by
@@ -3674,17 +3689,20 @@ var import_typescript3 = __toESM(require("typescript"), 1);
 var CONVENTIONAL_ENTRY_EXPORT_NAME = {
   contributions: "contributions",
   slotCatalogs: "slotCatalogs",
-  initializeEnhancement: "initializeEnhancement"
+  initializeEnhancement: "initializeEnhancement",
+  initializeModule: "initializeModule"
 };
 var CONVENTIONAL_ENTRY_DECLARATION_KIND = {
   contributions: "variable",
   slotCatalogs: "variable",
-  initializeEnhancement: "function"
+  initializeEnhancement: "function",
+  initializeModule: "function"
 };
 var CONVENTIONAL_ENTRY_FILENAME = {
   contributions: "contributions.ts",
   slotCatalogs: "slots.ts",
-  initializeEnhancement: "initialize.server.ts"
+  initializeEnhancement: "initialize.server.ts",
+  initializeModule: "initialize.server.ts"
 };
 function hasModifierKind(modifiers, kind) {
   return Boolean(modifiers?.some((m) => m.kind === kind));
@@ -3783,7 +3801,7 @@ function analyzeConventionalEntryExportWithTs(typescript, sourceText, kind, file
         }
         if (!isZeroArgumentInvocable(typescript, stmt.parameters)) {
           errors.push(
-            `"${entryName}" must be invocable with zero arguments (generated caller uses initializeEnhancement()); required parameters are forbidden \u2014 use optional, default, rest, or a this-parameter only`
+            `"${entryName}" must be invocable with zero arguments (generated caller uses ${entryName}()); required parameters are forbidden \u2014 use optional, default, rest, or a this-parameter only`
           );
           continue;
         }
@@ -4145,6 +4163,9 @@ function assertSlotCatalogsExport(source, pathLabel) {
 function assertInitializeEnhancementExport(source, pathLabel) {
   assertConventionalEntryExport(source, pathLabel, "initializeEnhancement");
 }
+function assertInitializeModuleExport(source, pathLabel) {
+  assertConventionalEntryExport(source, pathLabel, "initializeModule");
+}
 function assertClientSafeConventionalEntryImports(source, pathLabel, kind) {
   const { analysisErrors } = analyzeClientSafeEntryImports(
     source,
@@ -4664,30 +4685,47 @@ function deriveModuleLocaleLayers(registry, facts) {
   }
   return layers;
 }
-function emitModuleInitServerGenTs(input) {
+function moduleInitializerCalls(registry, facts) {
+  const installed = new Set(registry.modules.map((m) => m.name));
+  return facts.filter((f) => f.hasRootInitializeServer && installed.has(f.moduleName)).map((f) => f.moduleName).sort(compareNames).map((name, index) => {
+    if (!isValidModuleName(name)) {
+      throw new Error(`[ModuleRail] composition artifacts: invalid module name "${name}"`);
+    }
+    return {
+      exportName: "initializeModule",
+      guard: [name],
+      ident: `initializeModule${index}`,
+      importPath: `@/modules/${name}/initialize.server`
+    };
+  });
+}
+function enhancementInitializerCalls(registry, facts) {
   const calls = [];
-  const installed = new Set(input.registry.modules.map((m) => m.name));
-  let initializerIndex = 0;
-  for (const facts of [...input.facts].sort((a, b) => compareNames(a.moduleName, b.moduleName))) {
-    if (!installed.has(facts.moduleName)) continue;
-    const peers = activePeers(input.registry, facts.moduleName);
-    for (const enh of [...facts.enhancements].sort((a, b) => compareNames(a.peer, b.peer))) {
+  const installed = new Set(registry.modules.map((m) => m.name));
+  for (const f of [...facts].sort((a, b) => compareNames(a.moduleName, b.moduleName))) {
+    if (!installed.has(f.moduleName)) continue;
+    const peers = activePeers(registry, f.moduleName);
+    for (const enh of [...f.enhancements].sort((a, b) => compareNames(a.peer, b.peer))) {
       if (!enh.active || !peers.has(enh.peer)) continue;
       if (!enh.hasInitializeServer) continue;
-      const ident = `initializeEnhancement${initializerIndex++}`;
       calls.push({
-        owner: facts.moduleName,
-        peer: enh.peer,
-        ident,
-        importPath: `@/modules/${facts.moduleName}/enhancements/${enh.peer}/initialize.server`
+        exportName: "initializeEnhancement",
+        guard: [f.moduleName, enh.peer],
+        ident: `initializeEnhancement${calls.length}`,
+        importPath: `@/modules/${f.moduleName}/enhancements/${enh.peer}/initialize.server`
       });
     }
   }
-  const importLines = calls.map(
-    (c) => `import { initializeEnhancement as ${c.ident} } from ${JSON.stringify(c.importPath)};`
-  );
+  return calls;
+}
+function emitModuleInitServerGenTs(input) {
+  const moduleCalls = moduleInitializerCalls(input.registry, input.facts);
+  const enhancementCalls = enhancementInitializerCalls(input.registry, input.facts);
+  const calls = [...moduleCalls, ...enhancementCalls];
+  const importFor = (c) => `import { ${c.exportName} as ${c.ident} } from ${JSON.stringify(c.importPath)};`;
+  const importLines = moduleCalls.length === 0 ? calls.map(importFor) : [...calls].sort((a, b) => compareImportSpecifiers(a.importPath, b.importPath)).map(importFor);
   const callLines = calls.length === 0 ? ["      // Empty composition \u2014 no active enhancement initializers."] : calls.map(
-    (c) => `      if (enabled(${JSON.stringify(c.owner)}) && enabled(${JSON.stringify(c.peer)})) await ${c.ident}();`
+    (c) => `      if (${c.guard.map((name) => `enabled(${JSON.stringify(name)})`).join(" && ")}) await ${c.ident}();`
   );
   return [
     formatInitMarker(),
@@ -5137,6 +5175,7 @@ function buildRouteStubContent(input) {
     'import { notFound } from "next/navigation";',
     // simple-import-sort puts packages and "@/" aliases in separate groups.
     "",
+    'import { initializeActiveEnhancements } from "@/module-init.server.gen";',
     'import { isModuleEnabled, isMountHeadless } from "@/modules.gen";',
     `import Page from ${emitTsString(input.importModule)};`
   ];
@@ -5145,6 +5184,7 @@ function buildRouteStubContent(input) {
       `import { generateMetadata as sourceGenerateMetadata } from ${emitTsString(input.importModule)};`,
       "",
       "export async function generateMetadata(...args: Parameters<typeof sourceGenerateMetadata>) {",
+      "  await initializeActiveEnhancements();",
       ...emitGuardLines(guards, "return {};"),
       "  return sourceGenerateMetadata(...args);",
       "}"
@@ -5155,7 +5195,10 @@ function buildRouteStubContent(input) {
     "type PageProps =",
     "  Parameters<typeof Page> extends [infer P, ...unknown[]] ? NonNullable<P> : Record<never, never>;",
     "",
-    "export default function ModulePage(props: PageProps) {",
+    // Module and enhancement initializers run in this route's own module graph
+    // (memoized), so a cold server render sees their registrations.
+    "export default async function ModulePage(props: PageProps) {",
+    "  await initializeActiveEnhancements();",
     ...emitGuardLines(guards, "notFound();"),
     "  return <Page {...props} />;",
     "}",
@@ -5955,11 +5998,10 @@ var creationSourceBlueprintSchema = import_zod7.z.object({
    * `null`/absent means every feature Module: the platform stores that as the
    * explicit list of feature Modules in the published Blueprint version the fork
    * is cut from, so a Module a later Blueprint update adds arrives off. `[]` is
-   * refused: the platform serialises it to an empty
-   * `NEXT_PUBLIC_STARDECK_ENABLED_MODULES`, which the enablement parser reads
-   * back as "all" (`module-enablement.ts`) — the opposite of an empty selection.
+   * a custom app: no feature Module, Library Modules only (`resolvePlatformEnv`
+   * emits it as a set value naming no Module).
    */
-  enabledModules: import_zod7.z.array(moduleNameSchema).min(1, "Enable at least one Module").max(100).nullable().optional()
+  enabledModules: import_zod7.z.array(moduleNameSchema).max(100).nullable().optional()
 });
 var creationSourceSchema = import_zod7.z.discriminatedUnion("type", [
   creationSourceBlankSchema,
@@ -6954,6 +6996,9 @@ async function readConventionalEntryIfRealFile(path4, kind, presences, files) {
     case "initializeEnhancement":
       assertInitializeEnhancementExport(source, path4);
       break;
+    case "initializeModule":
+      assertInitializeModuleExport(source, path4);
+      break;
   }
   return source;
 }
@@ -6990,7 +7035,11 @@ async function collectCompositionEntryFacts(context, registry) {
   for (const mod of registry.modules) {
     const modulePath = `${MODULES_SANDBOX_DIR}/${mod.name}`;
     localeDirs.push(`${modulePath}/i18n`);
-    conventionalPaths.push(`${modulePath}/contributions.ts`, `${modulePath}/slots.ts`);
+    conventionalPaths.push(
+      `${modulePath}/contributions.ts`,
+      `${modulePath}/slots.ts`,
+      `${modulePath}/initialize.server.ts`
+    );
     for (const enh of mod.enhancements) {
       const peerDir = `${modulePath}/enhancements/${enh.peer}`;
       localeDirs.push(`${peerDir}/i18n`);
@@ -7078,6 +7127,17 @@ async function collectCompositionEntryFacts(context, registry) {
       }
     }
     const hasServerRegistrations = hasRealServerRegistrations(modulePath, conventionalPresences);
+    const hasRootInitializeServer = await readConventionalEntryIfRealFile(
+      `${modulePath}/initialize.server.ts`,
+      "initializeModule",
+      conventionalPresences,
+      files
+    ) != null;
+    if (hasRootInitializeServer) {
+      console.log(
+        `[ModuleRail] runId=${context.runId} module=${mod.name} has root initialize.server.ts (initializeModule)`
+      );
+    }
     const rootLocales = localesByDir.get(`${modulePath}/i18n`);
     if (rootLocales.length > 0 && !rootLocales.includes("en")) {
       throw new Error(
@@ -7118,6 +7178,7 @@ async function collectCompositionEntryFacts(context, registry) {
       hasRootContributions,
       hasRootSlots,
       hasServerRegistrations,
+      hasRootInitializeServer,
       rootLocales,
       enhancements
     });

package/dist/index.mjs

@@ -2068,11 +2068,18 @@ ${result.error}`);
 }
 
 // ../../packages/lib/src/server/sandbox/redact-secrets.ts
+var SECRET_NAME = String.raw`[A-Z][A-Z0-9_]*(?:_SECRET|_SECRET_KEY|_API_KEY|_KEY|_TOKEN|_PASSWORD)`;
+var SECRET_ASSIGNMENT = new RegExp(
+  String.raw`\b(${SECRET_NAME})\s*=\s*(?:'(?:[^']|'\\'')*'|"[^"]*"|[^\s&"',;}\]]+)`,
+  "g"
+);
+var JSON_SECRET_PAIR = new RegExp(
+  String.raw`"(${SECRET_NAME})"(\s*:\s*)"(?:[^"\\\n]|\\.)*"`,
+  "g"
+);
+var SECRET_QUOTE_OPENER = new RegExp(String.raw`\b${SECRET_NAME}\s*=\s*(['"])`, "g");
 function redactSecrets(text) {
-  return text.replace(/x-access-token:[^@\s]+@/g, "x-access-token:***@").replace(/https:\/\/(?!x-access-token:)[^/\s:@]+:[^/\s@]+@/gi, "https://***:***@").replace(/\b(gh[pousr]_)[A-Za-z0-9]+/g, "$1***").replace(/\b(github_pat_)[A-Za-z0-9_]+/g, "$1***").replace(/\b(postgres(?:ql)?:\/\/)([^:\s/@]+):([^@\s/]+)@/gi, "$1$2:***@").replace(/\b(npm_[A-Za-z0-9]+)/g, "npm_***").replace(/(_authToken=)([^\s&]+)/gi, "$1***").replace(
-    /\b([A-Z][A-Z0-9_]*(?:_SECRET|_SECRET_KEY|_API_KEY|_KEY|_TOKEN|_PASSWORD))\s*=\s*(?:'(?:[^']|'\\'')*'|"[^"]*"|[^\s&"',;}\]]+)/g,
-    "$1=***"
-  ).replace(/\b(Authorization:\s*(?:Bearer|Basic)\s+)\S+/gi, "$1***");
+  return text.replace(/x-access-token:[^@\s]+@/g, "x-access-token:***@").replace(/https:\/\/(?!x-access-token:)[^/\s:@]+:[^/\s@]+@/gi, "https://***:***@").replace(/\b(gh[pousr]_)[A-Za-z0-9]+/g, "$1***").replace(/\b(github_pat_)[A-Za-z0-9_]+/g, "$1***").replace(/\b(postgres(?:ql)?:\/\/)([^:\s/@]+):([^@\s/]+)@/gi, "$1$2:***@").replace(/\b(npm_[A-Za-z0-9]+)/g, "npm_***").replace(/(_authToken=)([^\s&]+)/gi, "$1***").replace(SECRET_ASSIGNMENT, "$1=***").replace(JSON_SECRET_PAIR, '"$1"$2"***"').replace(/\b(Authorization:\s*(?:Bearer|Basic)\s+)\S+/gi, "$1***");
 }
 
 // ../../packages/lib/src/server/sandbox/sh-quote.ts
@@ -2352,14 +2359,22 @@ var datastoreRequirementSchema = z2.object({
   /** Checked against the connected store's accessLevel at install. */
   access: z2.enum(["read", "write", "admin"]).default("write")
 }).strict();
-var permissionClaimSchema = z2.object({
+var MODULE_PERMISSION_DEFAULT_ROLES = ["manager", "member", "viewer"];
+var modulePermissionClaimSchema = z2.object({
   /**
    * Lowercase resource:action with one colon and no underscores. This grammar
    * is deliberately narrower than the platform permission tool's charset.
    */
   key: z2.string().regex(/^[a-z0-9][a-z0-9-]*:[a-z0-9][a-z0-9-]*$/, "must be a lowercase resource:action key").max(100, "must be at most 100 characters (platform permission tool limit)"),
   /** Human label for the deployment auth config row. */
-  description: descriptionSchema
+  description: descriptionSchema,
+  /**
+   * The default organization roles that hold this key when the platform
+   * first registers it on an app (a Blueprint fork, a Module install). Admin
+   * holds every key without being listed; External Viewer never holds one.
+   * Changing a role's grants afterwards is the organization's business.
+   */
+  roles: z2.array(z2.enum(MODULE_PERMISSION_DEFAULT_ROLES)).optional()
 }).strict();
 var seedBundleSchema = z2.object({
   table: tableNameSchema,
@@ -2442,7 +2457,7 @@ var moduleManifestSchema = z2.object({
    * Keys this module's guards enforce. Install registers them in deployment
    * auth config; registration only — declaring is never granting.
    */
-  permissions: z2.array(permissionClaimSchema).optional(),
+  permissions: z2.array(modulePermissionClaimSchema).optional(),
   /**
    * Optional starter rows for tables this module owns. Replay is
    * `INSERT ... ON CONFLICT (conflictTarget) DO NOTHING` — idempotent by
@@ -3655,17 +3670,20 @@ import ts3 from "typescript";
 var CONVENTIONAL_ENTRY_EXPORT_NAME = {
   contributions: "contributions",
   slotCatalogs: "slotCatalogs",
-  initializeEnhancement: "initializeEnhancement"
+  initializeEnhancement: "initializeEnhancement",
+  initializeModule: "initializeModule"
 };
 var CONVENTIONAL_ENTRY_DECLARATION_KIND = {
   contributions: "variable",
   slotCatalogs: "variable",
-  initializeEnhancement: "function"
+  initializeEnhancement: "function",
+  initializeModule: "function"
 };
 var CONVENTIONAL_ENTRY_FILENAME = {
   contributions: "contributions.ts",
   slotCatalogs: "slots.ts",
-  initializeEnhancement: "initialize.server.ts"
+  initializeEnhancement: "initialize.server.ts",
+  initializeModule: "initialize.server.ts"
 };
 function hasModifierKind(modifiers, kind) {
   return Boolean(modifiers?.some((m) => m.kind === kind));
@@ -3764,7 +3782,7 @@ function analyzeConventionalEntryExportWithTs(typescript, sourceText, kind, file
         }
         if (!isZeroArgumentInvocable(typescript, stmt.parameters)) {
           errors.push(
-            `"${entryName}" must be invocable with zero arguments (generated caller uses initializeEnhancement()); required parameters are forbidden \u2014 use optional, default, rest, or a this-parameter only`
+            `"${entryName}" must be invocable with zero arguments (generated caller uses ${entryName}()); required parameters are forbidden \u2014 use optional, default, rest, or a this-parameter only`
           );
           continue;
         }
@@ -4126,6 +4144,9 @@ function assertSlotCatalogsExport(source, pathLabel) {
 function assertInitializeEnhancementExport(source, pathLabel) {
   assertConventionalEntryExport(source, pathLabel, "initializeEnhancement");
 }
+function assertInitializeModuleExport(source, pathLabel) {
+  assertConventionalEntryExport(source, pathLabel, "initializeModule");
+}
 function assertClientSafeConventionalEntryImports(source, pathLabel, kind) {
   const { analysisErrors } = analyzeClientSafeEntryImports(
     source,
@@ -4645,30 +4666,47 @@ function deriveModuleLocaleLayers(registry, facts) {
   }
   return layers;
 }
-function emitModuleInitServerGenTs(input) {
+function moduleInitializerCalls(registry, facts) {
+  const installed = new Set(registry.modules.map((m) => m.name));
+  return facts.filter((f) => f.hasRootInitializeServer && installed.has(f.moduleName)).map((f) => f.moduleName).sort(compareNames).map((name, index) => {
+    if (!isValidModuleName(name)) {
+      throw new Error(`[ModuleRail] composition artifacts: invalid module name "${name}"`);
+    }
+    return {
+      exportName: "initializeModule",
+      guard: [name],
+      ident: `initializeModule${index}`,
+      importPath: `@/modules/${name}/initialize.server`
+    };
+  });
+}
+function enhancementInitializerCalls(registry, facts) {
   const calls = [];
-  const installed = new Set(input.registry.modules.map((m) => m.name));
-  let initializerIndex = 0;
-  for (const facts of [...input.facts].sort((a, b) => compareNames(a.moduleName, b.moduleName))) {
-    if (!installed.has(facts.moduleName)) continue;
-    const peers = activePeers(input.registry, facts.moduleName);
-    for (const enh of [...facts.enhancements].sort((a, b) => compareNames(a.peer, b.peer))) {
+  const installed = new Set(registry.modules.map((m) => m.name));
+  for (const f of [...facts].sort((a, b) => compareNames(a.moduleName, b.moduleName))) {
+    if (!installed.has(f.moduleName)) continue;
+    const peers = activePeers(registry, f.moduleName);
+    for (const enh of [...f.enhancements].sort((a, b) => compareNames(a.peer, b.peer))) {
       if (!enh.active || !peers.has(enh.peer)) continue;
       if (!enh.hasInitializeServer) continue;
-      const ident = `initializeEnhancement${initializerIndex++}`;
       calls.push({
-        owner: facts.moduleName,
-        peer: enh.peer,
-        ident,
-        importPath: `@/modules/${facts.moduleName}/enhancements/${enh.peer}/initialize.server`
+        exportName: "initializeEnhancement",
+        guard: [f.moduleName, enh.peer],
+        ident: `initializeEnhancement${calls.length}`,
+        importPath: `@/modules/${f.moduleName}/enhancements/${enh.peer}/initialize.server`
       });
     }
   }
-  const importLines = calls.map(
-    (c) => `import { initializeEnhancement as ${c.ident} } from ${JSON.stringify(c.importPath)};`
-  );
+  return calls;
+}
+function emitModuleInitServerGenTs(input) {
+  const moduleCalls = moduleInitializerCalls(input.registry, input.facts);
+  const enhancementCalls = enhancementInitializerCalls(input.registry, input.facts);
+  const calls = [...moduleCalls, ...enhancementCalls];
+  const importFor = (c) => `import { ${c.exportName} as ${c.ident} } from ${JSON.stringify(c.importPath)};`;
+  const importLines = moduleCalls.length === 0 ? calls.map(importFor) : [...calls].sort((a, b) => compareImportSpecifiers(a.importPath, b.importPath)).map(importFor);
   const callLines = calls.length === 0 ? ["      // Empty composition \u2014 no active enhancement initializers."] : calls.map(
-    (c) => `      if (enabled(${JSON.stringify(c.owner)}) && enabled(${JSON.stringify(c.peer)})) await ${c.ident}();`
+    (c) => `      if (${c.guard.map((name) => `enabled(${JSON.stringify(name)})`).join(" && ")}) await ${c.ident}();`
   );
   return [
     formatInitMarker(),
@@ -5118,6 +5156,7 @@ function buildRouteStubContent(input) {
     'import { notFound } from "next/navigation";',
     // simple-import-sort puts packages and "@/" aliases in separate groups.
     "",
+    'import { initializeActiveEnhancements } from "@/module-init.server.gen";',
     'import { isModuleEnabled, isMountHeadless } from "@/modules.gen";',
     `import Page from ${emitTsString(input.importModule)};`
   ];
@@ -5126,6 +5165,7 @@ function buildRouteStubContent(input) {
       `import { generateMetadata as sourceGenerateMetadata } from ${emitTsString(input.importModule)};`,
       "",
       "export async function generateMetadata(...args: Parameters<typeof sourceGenerateMetadata>) {",
+      "  await initializeActiveEnhancements();",
       ...emitGuardLines(guards, "return {};"),
       "  return sourceGenerateMetadata(...args);",
       "}"
@@ -5136,7 +5176,10 @@ function buildRouteStubContent(input) {
     "type PageProps =",
     "  Parameters<typeof Page> extends [infer P, ...unknown[]] ? NonNullable<P> : Record<never, never>;",
     "",
-    "export default function ModulePage(props: PageProps) {",
+    // Module and enhancement initializers run in this route's own module graph
+    // (memoized), so a cold server render sees their registrations.
+    "export default async function ModulePage(props: PageProps) {",
+    "  await initializeActiveEnhancements();",
     ...emitGuardLines(guards, "notFound();"),
     "  return <Page {...props} />;",
     "}",
@@ -5936,11 +5979,10 @@ var creationSourceBlueprintSchema = z7.object({
    * `null`/absent means every feature Module: the platform stores that as the
    * explicit list of feature Modules in the published Blueprint version the fork
    * is cut from, so a Module a later Blueprint update adds arrives off. `[]` is
-   * refused: the platform serialises it to an empty
-   * `NEXT_PUBLIC_STARDECK_ENABLED_MODULES`, which the enablement parser reads
-   * back as "all" (`module-enablement.ts`) — the opposite of an empty selection.
+   * a custom app: no feature Module, Library Modules only (`resolvePlatformEnv`
+   * emits it as a set value naming no Module).
    */
-  enabledModules: z7.array(moduleNameSchema).min(1, "Enable at least one Module").max(100).nullable().optional()
+  enabledModules: z7.array(moduleNameSchema).max(100).nullable().optional()
 });
 var creationSourceSchema = z7.discriminatedUnion("type", [
   creationSourceBlankSchema,
@@ -6935,6 +6977,9 @@ async function readConventionalEntryIfRealFile(path4, kind, presences, files) {
     case "initializeEnhancement":
       assertInitializeEnhancementExport(source, path4);
       break;
+    case "initializeModule":
+      assertInitializeModuleExport(source, path4);
+      break;
   }
   return source;
 }
@@ -6971,7 +7016,11 @@ async function collectCompositionEntryFacts(context, registry) {
   for (const mod of registry.modules) {
     const modulePath = `${MODULES_SANDBOX_DIR}/${mod.name}`;
     localeDirs.push(`${modulePath}/i18n`);
-    conventionalPaths.push(`${modulePath}/contributions.ts`, `${modulePath}/slots.ts`);
+    conventionalPaths.push(
+      `${modulePath}/contributions.ts`,
+      `${modulePath}/slots.ts`,
+      `${modulePath}/initialize.server.ts`
+    );
     for (const enh of mod.enhancements) {
       const peerDir = `${modulePath}/enhancements/${enh.peer}`;
       localeDirs.push(`${peerDir}/i18n`);
@@ -7059,6 +7108,17 @@ async function collectCompositionEntryFacts(context, registry) {
       }
     }
     const hasServerRegistrations = hasRealServerRegistrations(modulePath, conventionalPresences);
+    const hasRootInitializeServer = await readConventionalEntryIfRealFile(
+      `${modulePath}/initialize.server.ts`,
+      "initializeModule",
+      conventionalPresences,
+      files
+    ) != null;
+    if (hasRootInitializeServer) {
+      console.log(
+        `[ModuleRail] runId=${context.runId} module=${mod.name} has root initialize.server.ts (initializeModule)`
+      );
+    }
     const rootLocales = localesByDir.get(`${modulePath}/i18n`);
     if (rootLocales.length > 0 && !rootLocales.includes("en")) {
       throw new Error(
@@ -7099,6 +7159,7 @@ async function collectCompositionEntryFacts(context, registry) {
       hasRootContributions,
       hasRootSlots,
       hasServerRegistrations,
+      hasRootInitializeServer,
       rootLocales,
       enhancements
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stardeck-customer-apps/compose",
-  "version": "0.12.0",
+  "version": "0.14.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",
@@ -34,7 +34,7 @@
     "build": "rm -rf dist && tsup",
     "dev": "tsup --watch",
     "format": "prettier --write . && oxlint . --fix",
-    "typecheck": "tsc -p tsconfig.test.json",
+    "typecheck": "tsgo -p tsconfig.test.json",
     "lint": "oxlint src/",
     "test": "vitest run",
     "test:watch": "vitest"