@stardeck-customer-apps/eslint-plugin 1.2.0 → 1.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stardeck Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/SKILL.md

@@ -0,0 +1,124 @@
+# ESLint Plugin
+
+Custom ESLint rules for Stardeck customer apps. Requires ESLint 9+ flat config.
+
+## Installation
+
+```bash
+npm install @stardeck-customer-apps/eslint-plugin
+```
+
+## Setup
+
+```javascript
+// eslint.config.mjs
+import stardeckEslint from "@stardeck-customer-apps/eslint-plugin";
+
+export default [
+  // ... your other configs
+  stardeckEslint.configs.recommended,
+];
+```
+
+## Rules
+
+### `no-template-literal-classname`
+
+Disallows template literal interpolation in `className`. Use `cn()` instead.
+
+```tsx
+// Bad
+<div className={`px-4 ${isActive ? "bg-primary" : "bg-muted"}`} />
+
+// Good
+<div className={cn("px-4", isActive ? "bg-primary" : "bg-muted")} />
+```
+
+**Why?** Template literals in className break Tailwind IntelliSense and class merging.
+
+### `no-kysely-interactive-transaction`
+
+Disallows Kysely interactive and controlled transactions. The Kysely instance
+returned by `createDataStore()` is backed by the Neon HTTP driver, which cannot
+hold a transaction open across round-trips and throws at runtime:
+
+> NeonDialect doesn't support interactive transactions, while Kysely doesn't support batch requests (yet).
+
+```ts
+// Bad — throws at runtime
+await db.transaction().execute(async (trx) => {
+  await trx.insertInto("orders").values(order).execute();
+  await trx.updateTable("inventory").set({ count }).execute();
+});
+
+// Bad — controlled transactions are unsupported too
+const trx = await db.startTransaction().execute();
+
+// Good — fold the work into a single statement (CTE)
+await db
+  .with("new_order", (qb) => qb.insertInto("orders").values(order).returning("id"))
+  .updateTable("inventory")
+  .set({ count })
+  .execute();
+
+// Good — or run the statements sequentially
+await db.insertInto("orders").values(order).execute();
+await db.updateTable("inventory").set({ count }).execute();
+```
+
+**Why?** Drizzle's `db.transaction(cb)` and the Neon client's `sql.transaction([...])`
+take arguments, so only the zero-argument `db.transaction()` builder (and
+`db.startTransaction()`) — the Kysely interactive/controlled APIs — are flagged.
+
+### `no-module-internal-import`
+
+Vendored modules live at `src/modules/<name>/` with `index.ts` as the only public
+surface. Import other modules (and modules from app code) only through that index —
+e.g. `@/modules/booking`. Deep paths like `@/modules/booking/server/reservations`
+are an error (including type imports, `export * from`, and dynamic `import()`).
+A file inside a module may still import its own internals freely.
+
+```ts
+// Bad — reaches into module internals
+import { list } from "@/modules/booking/server/reservations";
+
+// Good — public surface only
+import { listReservations } from "@/modules/booking";
+```
+
+**Why?** Deep imports break module install/update isolation by coupling callers to
+files that can move or disappear when the module is swapped.
+
+### `no-server-import-in-conventional-entry`
+
+`contributions.ts` and `slots.ts` (root, or enhancement-scoped `contributions.ts`)
+are bundled into client-reachable composition artifacts. They must not directly
+import `server-only`, a Node builtin, a `.server` file, any `/server` module
+entry, or an enhancement root barrel (which may re-export `initialize.server`).
+`initialize.server.ts` itself is server-only by design and is not linted by
+this rule.
+
+```ts
+// contributions.ts — Bad
+import "server-only";
+import fs from "node:fs";
+import { handlers } from "@/modules/booking/server";
+import { initializeEnhancement } from "./initialize.server";
+
+// contributions.ts — Good
+import { z } from "zod";
+import { helper } from "./helpers";
+```
+
+**Why?** This is the immediate-import lint signal for a fail-closed contract also
+enforced by canonical AST evidence in the module structure collector and the
+install rail. Only the direct specifier is checked — it does not prove the
+entry's full import graph never reaches server code (that's the real Next
+client-build seam's job) — so do not add exemptions here to work around it.
+
+## Disable for a Line
+
+```tsx
+// eslint-disable-next-line @stardeck-customer-apps/eslint-plugin/no-template-literal-classname
+<div className={`legacy ${dynamicClass}`} />
+```

package/dist/index.cjs

@@ -139,8 +139,13 @@ function findSrcRoot(filename) {
   for (let i = 0; i < parts.length; i++) {
     if (parts[i] === "src") lastSrcIdx = i;
   }
-  if (lastSrcIdx === -1) return null;
-  return parts.slice(0, lastSrcIdx + 1).join("/");
+  if (lastSrcIdx !== -1) return parts.slice(0, lastSrcIdx + 1).join("/");
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (parts[i] === "apps" && parts[i + 1] === "web") {
+      return parts.slice(0, i + 2).concat("src").join("/");
+    }
+  }
+  return null;
 }
 function normalizePosixPath(raw) {
   const absolute = raw.startsWith("/");
@@ -193,6 +198,99 @@ function isPublicSurface(resolvedPath, srcRoot, moduleName) {
   if (resolvedPath === `${base}/index.tsx`) return true;
   return false;
 }
+function isModuleRoutesEntry(resolvedPath, srcRoot, moduleName) {
+  const prefix = `${srcRoot}/modules/${moduleName}/routes/`;
+  return resolvedPath === `${srcRoot}/modules/${moduleName}/routes` || resolvedPath.startsWith(prefix);
+}
+var RAIL_MARKER = "@stardeck-module-rail-generated";
+var I18N_GEN_MARKER = `// ${RAIL_MARKER} scope=i18n`;
+var LOCALE_BASENAME_REGEX = /^[a-z]{2,3}(?:-[A-Za-z0-9]+)*$/;
+var MAX_LOCALE_BASENAME_LENGTH = 35;
+function isRailGeneratedRouteStub(filename, sourceText) {
+  const posix = toPosix(filename);
+  if (!/\/src\/app\/.+\/page\.tsx$/.test(posix) && !/\/src\/app\/page\.tsx$/.test(posix)) {
+    return false;
+  }
+  const firstLine = sourceText.split(/\r?\n/, 1)[0]?.trim() ?? "";
+  return firstLine.startsWith(`// ${RAIL_MARKER} `) && firstLine.includes("scope=route ");
+}
+function isRailGeneratedCompositionImporter(filename, sourceText) {
+  const posix = toPosix(filename);
+  if (!/\/src\/(?:modules\.gen|module-contributions\.gen|module-i18n\.gen|module-init\.server\.gen)\.ts$/.test(
+    posix
+  )) {
+    return false;
+  }
+  const firstLine = sourceText.split(/\r?\n/, 1)[0]?.trim() ?? "";
+  if (!firstLine.startsWith(`// ${RAIL_MARKER} `)) return false;
+  return firstLine.includes("scope=contributions") || firstLine.includes("scope=i18n") || firstLine.includes("scope=init") || firstLine.includes("scope=registry");
+}
+function isConventionalCompositionEntry(resolvedPath, srcRoot, moduleName) {
+  const base = `${srcRoot}/modules/${moduleName}`;
+  const allowedExact = /* @__PURE__ */ new Set([
+    `${base}/contributions`,
+    `${base}/contributions.ts`,
+    `${base}/slots`,
+    `${base}/slots.ts`,
+    `${base}/i18n`,
+    `${base}/i18n/index`,
+    `${base}/i18n/index.ts`
+  ]);
+  if (allowedExact.has(resolvedPath)) return true;
+  const enhMatch = resolvedPath.match(
+    new RegExp(
+      `^${base.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/enhancements/([^/]+)/(contributions|initialize\\.server)(?:\\.ts)?$`
+    )
+  );
+  if (enhMatch) return true;
+  const enhI18n = resolvedPath.match(
+    new RegExp(
+      `^${base.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/enhancements/([^/]+)/i18n(?:/index(?:\\.ts)?)?$`
+    )
+  );
+  return Boolean(enhI18n);
+}
+function isRailGeneratedI18nJsonImporter(filename, sourceText) {
+  const posix = toPosix(filename);
+  if (!/\/src\/module-i18n\.gen\.ts$/.test(posix)) return false;
+  const firstLine = sourceText.split(/\r?\n/, 1)[0]?.trim() ?? "";
+  return firstLine === I18N_GEN_MARKER;
+}
+function localeBasenameFromI18nJsonPath(resolvedPath, srcRoot, moduleName) {
+  const base = `${srcRoot}/modules/${moduleName}`;
+  const escaped = base.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const rootMatch = new RegExp(`^${escaped}/i18n/([^/]+)\\.json$`).exec(resolvedPath);
+  if (rootMatch) return rootMatch[1] ?? null;
+  const sliceMatch = new RegExp(`^${escaped}/enhancements/[^/]+/i18n/([^/]+)\\.json$`).exec(
+    resolvedPath
+  );
+  return sliceMatch ? sliceMatch[1] ?? null : null;
+}
+function isValidLocaleBasename(basename) {
+  return basename.length > 0 && basename.length <= MAX_LOCALE_BASENAME_LENGTH && LOCALE_BASENAME_REGEX.test(basename);
+}
+function isConventionalI18nJsonEntry(resolvedPath, srcRoot, moduleName) {
+  const basename = localeBasenameFromI18nJsonPath(resolvedPath, srcRoot, moduleName);
+  return basename != null && isValidLocaleBasename(basename);
+}
+function isRailGeneratedEndpointStub(filename, sourceText) {
+  const posix = toPosix(filename);
+  if (!/\/src\/app\/api\/.+\/route\.ts$/.test(posix)) return false;
+  const firstLine = sourceText.split(/\r?\n/, 1)[0]?.trim() ?? "";
+  return firstLine.startsWith(`// ${RAIL_MARKER} `) && (firstLine.includes("scope=root") || firstLine.includes("scope=enhancement:"));
+}
+function isEndpointHandlerEntry(resolvedPath, srcRoot, moduleName) {
+  const base = `${srcRoot}/modules/${moduleName}`;
+  if (resolvedPath === `${base}/server` || resolvedPath === `${base}/server/index` || resolvedPath === `${base}/server/index.ts`) {
+    return true;
+  }
+  const enh = resolvedPath.match(
+    new RegExp(
+      `^${base.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/enhancements/([^/]+)(?:/index(?:\\.ts)?)?$`
+    )
+  );
+  return Boolean(enh);
+}
 var rule3 = {
   meta: {
     type: "problem",
@@ -216,6 +314,11 @@ var rule3 = {
     }
     const root = srcRoot;
     const importerModule = getModuleName(toPosix(filename), root);
+    const sourceText = context.sourceCode.getText();
+    const railRouteStub = isRailGeneratedRouteStub(filename, sourceText);
+    const railCompositionImporter = isRailGeneratedCompositionImporter(filename, sourceText);
+    const railI18nJsonImporter = isRailGeneratedI18nJsonImporter(filename, sourceText);
+    const railEndpointStub = isRailGeneratedEndpointStub(filename, sourceText);
     function check(node, sourceNode) {
       if (!sourceNode || sourceNode.type !== "Literal") return;
       const value = sourceNode.value;
@@ -226,6 +329,14 @@ var rule3 = {
       if (!targetModule) return;
       if (isPublicSurface(resolved, root, targetModule)) return;
       if (importerModule === targetModule) return;
+      if (railRouteStub && isModuleRoutesEntry(resolved, root, targetModule)) return;
+      if (railCompositionImporter && isConventionalCompositionEntry(resolved, root, targetModule)) {
+        return;
+      }
+      if (railI18nJsonImporter && isConventionalI18nJsonEntry(resolved, root, targetModule)) {
+        return;
+      }
+      if (railEndpointStub && isEndpointHandlerEntry(resolved, root, targetModule)) return;
       context.report({
         node,
         messageId: "noInternalImport",
@@ -245,17 +356,216 @@ var rule3 = {
       },
       ExportAllDeclaration(node) {
         check(node, node.source);
+      },
+      // Literal CommonJS `require("...")` — same isolation rule as ESM imports.
+      CallExpression(node) {
+        const call = node;
+        if (call.callee?.type !== "Identifier" || call.callee.name !== "require") return;
+        const arg0 = call.arguments?.[0];
+        if (!arg0 || arg0.type !== "Literal" || typeof arg0.value !== "string") return;
+        check(node, arg0);
+      },
+      // TypeScript `import x = require("...")` (TS-ESLint AST).
+      TSImportEqualsDeclaration(node) {
+        const decl = node;
+        const ref = decl.moduleReference;
+        if (!ref || ref.type !== "TSExternalModuleReference") return;
+        const expression = ref.expression;
+        if (!expression || expression.type !== "Literal" || typeof expression.value !== "string") {
+          return;
+        }
+        check(node, expression);
       }
     };
   }
 };
 var no_module_internal_import_default = rule3;
 
+// src/rules/no-server-import-in-conventional-entry.ts
+var import_node_path2 = __toESM(require("path"), 1);
+function toPosix2(filePath) {
+  return filePath.split(import_node_path2.default.sep).join("/");
+}
+function isClientSafeConventionalEntry(filename) {
+  const posix = toPosix2(filename);
+  return /\/src\/modules\/[^/]+\/(?:contributions|slots)\.ts$/.test(posix) || /\/src\/modules\/[^/]+\/enhancements\/[^/]+\/contributions\.ts$/.test(posix);
+}
+var NODE_BUILTIN_MODULE_NAMES = /* @__PURE__ */ new Set([
+  "assert",
+  "async_hooks",
+  "buffer",
+  "child_process",
+  "cluster",
+  "console",
+  "constants",
+  "crypto",
+  "dgram",
+  "diagnostics_channel",
+  "dns",
+  "domain",
+  "events",
+  "fs",
+  "http",
+  "http2",
+  "https",
+  "inspector",
+  "module",
+  "net",
+  "os",
+  "path",
+  "perf_hooks",
+  "process",
+  "punycode",
+  "querystring",
+  "readline",
+  "repl",
+  "stream",
+  "string_decoder",
+  "sys",
+  "timers",
+  "tls",
+  "trace_events",
+  "tty",
+  "url",
+  "util",
+  "v8",
+  "vm",
+  "wasi",
+  "worker_threads",
+  "zlib"
+]);
+function isNodeBuiltinImportSpecifier(specifier) {
+  const withoutNodePrefix = specifier.startsWith("node:") ? specifier.slice("node:".length) : specifier;
+  if (withoutNodePrefix.startsWith("@")) return false;
+  const firstSegment = withoutNodePrefix.split("/")[0] ?? withoutNodePrefix;
+  return specifier.startsWith("node:") || NODE_BUILTIN_MODULE_NAMES.has(firstSegment);
+}
+function classifyForbiddenSpecifier(specifier) {
+  if (specifier === "server-only") {
+    return {
+      reason: "server-only-package",
+      message: `import of "server-only" package "${specifier}" is forbidden in a client-safe conventional entry`
+    };
+  }
+  if (isNodeBuiltinImportSpecifier(specifier)) {
+    return {
+      reason: "node-builtin",
+      message: `import of Node builtin "${specifier}" is forbidden in a client-safe conventional entry`
+    };
+  }
+  const pathPart = specifier.split(/[?#]/, 1)[0] ?? specifier;
+  const segments = pathPart.split("/").filter((s) => s.length > 0 && s !== ".");
+  if (/\.server(?:\.[cm]?[tj]sx?)?$/.test(pathPart)) {
+    return {
+      reason: "dot-server-file",
+      message: `import of a ".server" file "${specifier}" is forbidden in a client-safe conventional entry`
+    };
+  }
+  if (segments.some((seg) => seg === "server")) {
+    return {
+      reason: "server-path-segment",
+      message: `import reaching a "/server" module entry "${specifier}" is forbidden in a client-safe conventional entry`
+    };
+  }
+  const enhIdx = segments.lastIndexOf("enhancements");
+  if (enhIdx !== -1) {
+    const rest = segments.slice(enhIdx + 1);
+    const isRootBarrel = rest.length === 1 || rest.length === 2 && (rest[1] === "index" || rest[1] === "index.ts");
+    if (isRootBarrel) {
+      return {
+        reason: "enhancement-root-entry",
+        message: `import of enhancement root entry "${specifier}" is forbidden in a client-safe conventional entry (may carry server initialization)`
+      };
+    }
+  }
+  return null;
+}
+var rule4 = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow direct server-only / node builtin / .server / /server / enhancement-root imports inside contributions.ts and slots.ts, which are bundled into client-reachable composition artifacts",
+      recommended: true
+    },
+    messages: {
+      forbiddenServerImport: "{{message}}"
+    },
+    schema: []
+  },
+  create(context) {
+    const filename = context.filename;
+    if (!filename || filename === "<input>" || filename === "<text>") {
+      return {};
+    }
+    if (!isClientSafeConventionalEntry(filename)) {
+      return {};
+    }
+    function check(node, sourceNode) {
+      if (!sourceNode || sourceNode.type !== "Literal") return;
+      const value = sourceNode.value;
+      if (typeof value !== "string") return;
+      const forbidden = classifyForbiddenSpecifier(value);
+      if (!forbidden) return;
+      context.report({
+        node,
+        messageId: "forbiddenServerImport",
+        data: { message: forbidden.message }
+      });
+    }
+    return {
+      ImportDeclaration(node) {
+        check(node, node.source);
+      },
+      ImportExpression(node) {
+        const src = node.source;
+        check(node, src);
+      },
+      ExportNamedDeclaration(node) {
+        check(node, node.source);
+      },
+      ExportAllDeclaration(node) {
+        check(node, node.source);
+      },
+      // Literal CommonJS `require("...")` — same client-bundle risk as ESM import.
+      CallExpression(node) {
+        const call = node;
+        if (call.callee?.type !== "Identifier" || call.callee.name !== "require") return;
+        const arg0 = call.arguments?.[0];
+        if (!arg0 || arg0.type !== "Literal" || typeof arg0.value !== "string") return;
+        const forbidden = classifyForbiddenSpecifier(arg0.value);
+        if (!forbidden) return;
+        context.report({
+          node,
+          messageId: "forbiddenServerImport",
+          data: { message: forbidden.message }
+        });
+      },
+      // TypeScript `import x = require("...")` (TS-ESLint AST).
+      TSImportEqualsDeclaration(node) {
+        const decl = node;
+        const ref = decl.moduleReference;
+        if (!ref || ref.type !== "TSExternalModuleReference") return;
+        const expr = ref.expression;
+        if (!expr || expr.type !== "Literal" || typeof expr.value !== "string") return;
+        const forbidden = classifyForbiddenSpecifier(expr.value);
+        if (!forbidden) return;
+        context.report({
+          node,
+          messageId: "forbiddenServerImport",
+          data: { message: forbidden.message }
+        });
+      }
+    };
+  }
+};
+var no_server_import_in_conventional_entry_default = rule4;
+
 // src/rules/index.ts
 var rules = {
   "no-template-literal-classname": no_template_literal_classname_default,
   "no-kysely-interactive-transaction": no_kysely_interactive_transaction_default,
-  "no-module-internal-import": no_module_internal_import_default
+  "no-module-internal-import": no_module_internal_import_default,
+  "no-server-import-in-conventional-entry": no_server_import_in_conventional_entry_default
 };
 
 // src/configs/recommended.ts
@@ -269,7 +579,8 @@ var recommended = {
   rules: {
     [`${pluginName}/no-template-literal-classname`]: "error",
     [`${pluginName}/no-kysely-interactive-transaction`]: "error",
-    [`${pluginName}/no-module-internal-import`]: "error"
+    [`${pluginName}/no-module-internal-import`]: "error",
+    [`${pluginName}/no-server-import-in-conventional-entry`]: "error"
   }
 };
 

package/dist/index.d.cts

@@ -5,6 +5,7 @@ declare const rules: {
     "no-template-literal-classname": eslint.Rule.RuleModule;
     "no-kysely-interactive-transaction": eslint.Rule.RuleModule;
     "no-module-internal-import": eslint.Rule.RuleModule;
+    "no-server-import-in-conventional-entry": eslint.Rule.RuleModule;
 };
 
 declare const configs: Record<string, Linter.Config>;

package/dist/index.d.ts

@@ -5,6 +5,7 @@ declare const rules: {
     "no-template-literal-classname": eslint.Rule.RuleModule;
     "no-kysely-interactive-transaction": eslint.Rule.RuleModule;
     "no-module-internal-import": eslint.Rule.RuleModule;
+    "no-server-import-in-conventional-entry": eslint.Rule.RuleModule;
 };
 
 declare const configs: Record<string, Linter.Config>;

package/dist/index.js

@@ -101,8 +101,13 @@ function findSrcRoot(filename) {
   for (let i = 0; i < parts.length; i++) {
     if (parts[i] === "src") lastSrcIdx = i;
   }
-  if (lastSrcIdx === -1) return null;
-  return parts.slice(0, lastSrcIdx + 1).join("/");
+  if (lastSrcIdx !== -1) return parts.slice(0, lastSrcIdx + 1).join("/");
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (parts[i] === "apps" && parts[i + 1] === "web") {
+      return parts.slice(0, i + 2).concat("src").join("/");
+    }
+  }
+  return null;
 }
 function normalizePosixPath(raw) {
   const absolute = raw.startsWith("/");
@@ -155,6 +160,99 @@ function isPublicSurface(resolvedPath, srcRoot, moduleName) {
   if (resolvedPath === `${base}/index.tsx`) return true;
   return false;
 }
+function isModuleRoutesEntry(resolvedPath, srcRoot, moduleName) {
+  const prefix = `${srcRoot}/modules/${moduleName}/routes/`;
+  return resolvedPath === `${srcRoot}/modules/${moduleName}/routes` || resolvedPath.startsWith(prefix);
+}
+var RAIL_MARKER = "@stardeck-module-rail-generated";
+var I18N_GEN_MARKER = `// ${RAIL_MARKER} scope=i18n`;
+var LOCALE_BASENAME_REGEX = /^[a-z]{2,3}(?:-[A-Za-z0-9]+)*$/;
+var MAX_LOCALE_BASENAME_LENGTH = 35;
+function isRailGeneratedRouteStub(filename, sourceText) {
+  const posix = toPosix(filename);
+  if (!/\/src\/app\/.+\/page\.tsx$/.test(posix) && !/\/src\/app\/page\.tsx$/.test(posix)) {
+    return false;
+  }
+  const firstLine = sourceText.split(/\r?\n/, 1)[0]?.trim() ?? "";
+  return firstLine.startsWith(`// ${RAIL_MARKER} `) && firstLine.includes("scope=route ");
+}
+function isRailGeneratedCompositionImporter(filename, sourceText) {
+  const posix = toPosix(filename);
+  if (!/\/src\/(?:modules\.gen|module-contributions\.gen|module-i18n\.gen|module-init\.server\.gen)\.ts$/.test(
+    posix
+  )) {
+    return false;
+  }
+  const firstLine = sourceText.split(/\r?\n/, 1)[0]?.trim() ?? "";
+  if (!firstLine.startsWith(`// ${RAIL_MARKER} `)) return false;
+  return firstLine.includes("scope=contributions") || firstLine.includes("scope=i18n") || firstLine.includes("scope=init") || firstLine.includes("scope=registry");
+}
+function isConventionalCompositionEntry(resolvedPath, srcRoot, moduleName) {
+  const base = `${srcRoot}/modules/${moduleName}`;
+  const allowedExact = /* @__PURE__ */ new Set([
+    `${base}/contributions`,
+    `${base}/contributions.ts`,
+    `${base}/slots`,
+    `${base}/slots.ts`,
+    `${base}/i18n`,
+    `${base}/i18n/index`,
+    `${base}/i18n/index.ts`
+  ]);
+  if (allowedExact.has(resolvedPath)) return true;
+  const enhMatch = resolvedPath.match(
+    new RegExp(
+      `^${base.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/enhancements/([^/]+)/(contributions|initialize\\.server)(?:\\.ts)?$`
+    )
+  );
+  if (enhMatch) return true;
+  const enhI18n = resolvedPath.match(
+    new RegExp(
+      `^${base.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/enhancements/([^/]+)/i18n(?:/index(?:\\.ts)?)?$`
+    )
+  );
+  return Boolean(enhI18n);
+}
+function isRailGeneratedI18nJsonImporter(filename, sourceText) {
+  const posix = toPosix(filename);
+  if (!/\/src\/module-i18n\.gen\.ts$/.test(posix)) return false;
+  const firstLine = sourceText.split(/\r?\n/, 1)[0]?.trim() ?? "";
+  return firstLine === I18N_GEN_MARKER;
+}
+function localeBasenameFromI18nJsonPath(resolvedPath, srcRoot, moduleName) {
+  const base = `${srcRoot}/modules/${moduleName}`;
+  const escaped = base.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const rootMatch = new RegExp(`^${escaped}/i18n/([^/]+)\\.json$`).exec(resolvedPath);
+  if (rootMatch) return rootMatch[1] ?? null;
+  const sliceMatch = new RegExp(`^${escaped}/enhancements/[^/]+/i18n/([^/]+)\\.json$`).exec(
+    resolvedPath
+  );
+  return sliceMatch ? sliceMatch[1] ?? null : null;
+}
+function isValidLocaleBasename(basename) {
+  return basename.length > 0 && basename.length <= MAX_LOCALE_BASENAME_LENGTH && LOCALE_BASENAME_REGEX.test(basename);
+}
+function isConventionalI18nJsonEntry(resolvedPath, srcRoot, moduleName) {
+  const basename = localeBasenameFromI18nJsonPath(resolvedPath, srcRoot, moduleName);
+  return basename != null && isValidLocaleBasename(basename);
+}
+function isRailGeneratedEndpointStub(filename, sourceText) {
+  const posix = toPosix(filename);
+  if (!/\/src\/app\/api\/.+\/route\.ts$/.test(posix)) return false;
+  const firstLine = sourceText.split(/\r?\n/, 1)[0]?.trim() ?? "";
+  return firstLine.startsWith(`// ${RAIL_MARKER} `) && (firstLine.includes("scope=root") || firstLine.includes("scope=enhancement:"));
+}
+function isEndpointHandlerEntry(resolvedPath, srcRoot, moduleName) {
+  const base = `${srcRoot}/modules/${moduleName}`;
+  if (resolvedPath === `${base}/server` || resolvedPath === `${base}/server/index` || resolvedPath === `${base}/server/index.ts`) {
+    return true;
+  }
+  const enh = resolvedPath.match(
+    new RegExp(
+      `^${base.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/enhancements/([^/]+)(?:/index(?:\\.ts)?)?$`
+    )
+  );
+  return Boolean(enh);
+}
 var rule3 = {
   meta: {
     type: "problem",
@@ -178,6 +276,11 @@ var rule3 = {
     }
     const root = srcRoot;
     const importerModule = getModuleName(toPosix(filename), root);
+    const sourceText = context.sourceCode.getText();
+    const railRouteStub = isRailGeneratedRouteStub(filename, sourceText);
+    const railCompositionImporter = isRailGeneratedCompositionImporter(filename, sourceText);
+    const railI18nJsonImporter = isRailGeneratedI18nJsonImporter(filename, sourceText);
+    const railEndpointStub = isRailGeneratedEndpointStub(filename, sourceText);
     function check(node, sourceNode) {
       if (!sourceNode || sourceNode.type !== "Literal") return;
       const value = sourceNode.value;
@@ -188,6 +291,14 @@ var rule3 = {
       if (!targetModule) return;
       if (isPublicSurface(resolved, root, targetModule)) return;
       if (importerModule === targetModule) return;
+      if (railRouteStub && isModuleRoutesEntry(resolved, root, targetModule)) return;
+      if (railCompositionImporter && isConventionalCompositionEntry(resolved, root, targetModule)) {
+        return;
+      }
+      if (railI18nJsonImporter && isConventionalI18nJsonEntry(resolved, root, targetModule)) {
+        return;
+      }
+      if (railEndpointStub && isEndpointHandlerEntry(resolved, root, targetModule)) return;
       context.report({
         node,
         messageId: "noInternalImport",
@@ -207,17 +318,216 @@ var rule3 = {
       },
       ExportAllDeclaration(node) {
         check(node, node.source);
+      },
+      // Literal CommonJS `require("...")` — same isolation rule as ESM imports.
+      CallExpression(node) {
+        const call = node;
+        if (call.callee?.type !== "Identifier" || call.callee.name !== "require") return;
+        const arg0 = call.arguments?.[0];
+        if (!arg0 || arg0.type !== "Literal" || typeof arg0.value !== "string") return;
+        check(node, arg0);
+      },
+      // TypeScript `import x = require("...")` (TS-ESLint AST).
+      TSImportEqualsDeclaration(node) {
+        const decl = node;
+        const ref = decl.moduleReference;
+        if (!ref || ref.type !== "TSExternalModuleReference") return;
+        const expression = ref.expression;
+        if (!expression || expression.type !== "Literal" || typeof expression.value !== "string") {
+          return;
+        }
+        check(node, expression);
       }
     };
   }
 };
 var no_module_internal_import_default = rule3;
 
+// src/rules/no-server-import-in-conventional-entry.ts
+import path2 from "path";
+function toPosix2(filePath) {
+  return filePath.split(path2.sep).join("/");
+}
+function isClientSafeConventionalEntry(filename) {
+  const posix = toPosix2(filename);
+  return /\/src\/modules\/[^/]+\/(?:contributions|slots)\.ts$/.test(posix) || /\/src\/modules\/[^/]+\/enhancements\/[^/]+\/contributions\.ts$/.test(posix);
+}
+var NODE_BUILTIN_MODULE_NAMES = /* @__PURE__ */ new Set([
+  "assert",
+  "async_hooks",
+  "buffer",
+  "child_process",
+  "cluster",
+  "console",
+  "constants",
+  "crypto",
+  "dgram",
+  "diagnostics_channel",
+  "dns",
+  "domain",
+  "events",
+  "fs",
+  "http",
+  "http2",
+  "https",
+  "inspector",
+  "module",
+  "net",
+  "os",
+  "path",
+  "perf_hooks",
+  "process",
+  "punycode",
+  "querystring",
+  "readline",
+  "repl",
+  "stream",
+  "string_decoder",
+  "sys",
+  "timers",
+  "tls",
+  "trace_events",
+  "tty",
+  "url",
+  "util",
+  "v8",
+  "vm",
+  "wasi",
+  "worker_threads",
+  "zlib"
+]);
+function isNodeBuiltinImportSpecifier(specifier) {
+  const withoutNodePrefix = specifier.startsWith("node:") ? specifier.slice("node:".length) : specifier;
+  if (withoutNodePrefix.startsWith("@")) return false;
+  const firstSegment = withoutNodePrefix.split("/")[0] ?? withoutNodePrefix;
+  return specifier.startsWith("node:") || NODE_BUILTIN_MODULE_NAMES.has(firstSegment);
+}
+function classifyForbiddenSpecifier(specifier) {
+  if (specifier === "server-only") {
+    return {
+      reason: "server-only-package",
+      message: `import of "server-only" package "${specifier}" is forbidden in a client-safe conventional entry`
+    };
+  }
+  if (isNodeBuiltinImportSpecifier(specifier)) {
+    return {
+      reason: "node-builtin",
+      message: `import of Node builtin "${specifier}" is forbidden in a client-safe conventional entry`
+    };
+  }
+  const pathPart = specifier.split(/[?#]/, 1)[0] ?? specifier;
+  const segments = pathPart.split("/").filter((s) => s.length > 0 && s !== ".");
+  if (/\.server(?:\.[cm]?[tj]sx?)?$/.test(pathPart)) {
+    return {
+      reason: "dot-server-file",
+      message: `import of a ".server" file "${specifier}" is forbidden in a client-safe conventional entry`
+    };
+  }
+  if (segments.some((seg) => seg === "server")) {
+    return {
+      reason: "server-path-segment",
+      message: `import reaching a "/server" module entry "${specifier}" is forbidden in a client-safe conventional entry`
+    };
+  }
+  const enhIdx = segments.lastIndexOf("enhancements");
+  if (enhIdx !== -1) {
+    const rest = segments.slice(enhIdx + 1);
+    const isRootBarrel = rest.length === 1 || rest.length === 2 && (rest[1] === "index" || rest[1] === "index.ts");
+    if (isRootBarrel) {
+      return {
+        reason: "enhancement-root-entry",
+        message: `import of enhancement root entry "${specifier}" is forbidden in a client-safe conventional entry (may carry server initialization)`
+      };
+    }
+  }
+  return null;
+}
+var rule4 = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow direct server-only / node builtin / .server / /server / enhancement-root imports inside contributions.ts and slots.ts, which are bundled into client-reachable composition artifacts",
+      recommended: true
+    },
+    messages: {
+      forbiddenServerImport: "{{message}}"
+    },
+    schema: []
+  },
+  create(context) {
+    const filename = context.filename;
+    if (!filename || filename === "<input>" || filename === "<text>") {
+      return {};
+    }
+    if (!isClientSafeConventionalEntry(filename)) {
+      return {};
+    }
+    function check(node, sourceNode) {
+      if (!sourceNode || sourceNode.type !== "Literal") return;
+      const value = sourceNode.value;
+      if (typeof value !== "string") return;
+      const forbidden = classifyForbiddenSpecifier(value);
+      if (!forbidden) return;
+      context.report({
+        node,
+        messageId: "forbiddenServerImport",
+        data: { message: forbidden.message }
+      });
+    }
+    return {
+      ImportDeclaration(node) {
+        check(node, node.source);
+      },
+      ImportExpression(node) {
+        const src = node.source;
+        check(node, src);
+      },
+      ExportNamedDeclaration(node) {
+        check(node, node.source);
+      },
+      ExportAllDeclaration(node) {
+        check(node, node.source);
+      },
+      // Literal CommonJS `require("...")` — same client-bundle risk as ESM import.
+      CallExpression(node) {
+        const call = node;
+        if (call.callee?.type !== "Identifier" || call.callee.name !== "require") return;
+        const arg0 = call.arguments?.[0];
+        if (!arg0 || arg0.type !== "Literal" || typeof arg0.value !== "string") return;
+        const forbidden = classifyForbiddenSpecifier(arg0.value);
+        if (!forbidden) return;
+        context.report({
+          node,
+          messageId: "forbiddenServerImport",
+          data: { message: forbidden.message }
+        });
+      },
+      // TypeScript `import x = require("...")` (TS-ESLint AST).
+      TSImportEqualsDeclaration(node) {
+        const decl = node;
+        const ref = decl.moduleReference;
+        if (!ref || ref.type !== "TSExternalModuleReference") return;
+        const expr = ref.expression;
+        if (!expr || expr.type !== "Literal" || typeof expr.value !== "string") return;
+        const forbidden = classifyForbiddenSpecifier(expr.value);
+        if (!forbidden) return;
+        context.report({
+          node,
+          messageId: "forbiddenServerImport",
+          data: { message: forbidden.message }
+        });
+      }
+    };
+  }
+};
+var no_server_import_in_conventional_entry_default = rule4;
+
 // src/rules/index.ts
 var rules = {
   "no-template-literal-classname": no_template_literal_classname_default,
   "no-kysely-interactive-transaction": no_kysely_interactive_transaction_default,
-  "no-module-internal-import": no_module_internal_import_default
+  "no-module-internal-import": no_module_internal_import_default,
+  "no-server-import-in-conventional-entry": no_server_import_in_conventional_entry_default
 };
 
 // src/configs/recommended.ts
@@ -231,7 +541,8 @@ var recommended = {
   rules: {
     [`${pluginName}/no-template-literal-classname`]: "error",
     [`${pluginName}/no-kysely-interactive-transaction`]: "error",
-    [`${pluginName}/no-module-internal-import`]: "error"
+    [`${pluginName}/no-module-internal-import`]: "error",
+    [`${pluginName}/no-server-import-in-conventional-entry`]: "error"
   }
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stardeck-customer-apps/eslint-plugin",
-  "version": "1.2.0",
+  "version": "1.5.0",
   "description": "Custom ESLint rules for Stardeck customer apps",
   "type": "module",
   "main": "dist/index.js",
@@ -11,7 +11,8 @@
     "access": "public"
   },
   "files": [
-    "dist"
+    "dist",
+    "SKILL.md"
   ],
   "exports": {
     ".": {