@nage-api/eslint-config 1.0.0-beta.2

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,131 @@
+# @nage-api/eslint-config
+
+The shared strict ESLint flat config (PLAN.md §20), and the registry that makes
+the layered dependency rule of §7.2 a lint error rather than a convention.
+
+Two jobs in one package, because they are the same job. §13 asks the framework to
+hold itself to `no-explicit-any`, the `no-unsafe-*` family and
+`no-floating-promises`; §7.2 asks it to keep dependencies pointing downward. Both
+are rules nobody can enforce by reading a diff, so both are here.
+
+The legacy framework had an `eslint.config.mjs` too. It extended
+`recommendedTypeChecked` and then turned the guarantees back off:
+`no-explicit-any: off`, the unsafe family off, `no-floating-promises` at `warn`,
+`no-unused-vars` at `warn` (§2.5). The result was 146 explicit `any` annotations
+in non-test source and a `ModelService<M>` whose generic was undone by `body: any`
+at the `Job` boundary (§5.1). A rule at `warn` in a repository with no lint step
+in CI (§2.5) is a comment.
+
+## Usage
+
+```js
+// eslint.config.mjs
+import { nageEslintConfig } from '@nage-api/eslint-config';
+
+export default nageEslintConfig({ tsconfigRootDir: import.meta.dirname });
+```
+
+`tsconfigRootDir` is required rather than defaulted, and `projectService: true`
+means the type-aware rules resolve every file through the nearest real
+`tsconfig.json`. A default would guess the root, and the failure mode of a wrong
+guess is not an error but silence: type-aware rules find nothing in a file the
+service could not place, so the strictest rules in the config become the easiest
+to lose.
+
+ESLint 10 is the peer dependency; `typescript-eslint`, `globals` and
+`eslint-config-prettier` are this package's own, so a consumer installs ESLint and
+this and nothing else. The Prettier compatibility block is applied last on
+purpose — it turns off the stylistic rules Prettier owns, and a block after it
+would quietly reinstate them.
+
+## What it enforces
+
+| Area                      | Rules                                                                                                                                          |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| Type safety (PLAN.md §13) | `no-explicit-any`, the `no-unsafe-*` family, `no-floating-promises`, `no-misused-promises`, `explicit-module-boundary-types` on package source |
+| Security (PLAN.md §12)    | `Math.random()` is banned — use `node:crypto`                                                                                                  |
+| Consistency               | `consistent-type-imports`/`-exports`, `eqeqeq`, `prefer-const`, `no-console` (warn/error allowed)                                              |
+| Layering (PLAN.md §7.2)   | generated `no-restricted-imports` rules — see below                                                                                            |
+
+The `Math.random()` ban is a `no-restricted-syntax` selector on
+`Math.random`, and it exists because of two specific functions: legacy `otp()`
+and `randomString()` in `core.utils.ts` generated one-time codes and tokens from
+a non-cryptographic PRNG (§12). Neither call looked wrong, which is the point of
+enforcing it at the syntax level rather than in review.
+
+Four blocks relax the baseline where a rule would fail honest code. Test files
+drop the unsafe-assignment family and `unbound-method` — supertest types its
+responses as `any`, and naming a method to identify a route handler is not a
+`this`-binding mistake. `*.module.ts` drops `no-extraneous-class`, because a
+`forRoot`-only module is the framework's own idiom and `@Module({})` needs a class
+to decorate. Plain JS gets `disableTypeChecked` and `no-console: off`, since
+tooling scripts print. Production source in `packages/*/src` keeps every rule and
+adds `explicit-module-boundary-types`.
+
+## Dependency boundaries
+
+`layers.js` is the single source of truth for the package graph:
+
+```
+apps → @nage-api/cli → drivers → feature packages → @nage-api/core → @nage-api/contracts
+```
+
+- Dependencies point **downward only**.
+- Feature packages may not import each other; they collaborate through
+  `@nage-api/contracts` interfaces and `@nage-api/core` DI tokens.
+- `@nage-api/contracts` is types-only: no Nest, no `rxjs`, no `zod`, no runtime deps.
+- Exceptions are explicit and justified in `ALLOWED_EXCEPTIONS` (e.g. a driver
+  may depend on the base package whose ports it implements).
+
+Every package — including ones not yet scaffolded — is registered in
+`PACKAGE_REGISTRY` with its directory and layer, so a new package cannot enter
+the workspace without declaring where it sits in the graph.
+
+`boundaries.js` turns that registry into a pair of flat-config blocks per package,
+scoping a `no-restricted-imports` pattern list to that package's directory: one for
+its TypeScript sources, one for its plain-JS tooling files. The TypeScript block
+uses the `@typescript-eslint` variant of the rule, so `import type` cannot be used
+to sidestep the direction — a type-only import is still a reason to open the other
+package's source, which is the coupling the rule is about.
+
+The same registry backs two checks ESLint cannot make:
+
+- `tools/boundaries/check-manifests.mjs` reads every `package.json`, so a
+  violation cannot slip through as a declared-but-dynamically-imported
+  dependency. It also fails a package that is unregistered, or whose directory
+  disagrees with the registry.
+- `tools/boundaries/check-relative-imports.mjs` catches
+  `import '../../data/src/thing.js'`, which is invisible to
+  `no-restricted-imports` because the specifier never names a package.
+
+And `tools/boundaries/verify-enforcement.mjs` proves in CI that each of those
+layers actually rejects a violation, by building six deliberately broken fixtures
+in a throwaway tree. A rule nobody has watched fire is a rule nobody can trust,
+and the failure mode here is quiet: a glob that stops matching disables a rule
+without any error to notice.
+
+## Consuming it in a generated workspace
+
+The intent (§20) is that a generated app extends the same config the framework
+holds itself to, and the boundary blocks are inert there: each is globbed to one
+registry directory (`packages/auth/**`, `packages/data/data-sql/**`, …), and a
+generated workspace has none of them. A generated app gets the §13 type-safety
+rules and the `Math.random()` ban, and no layering.
+
+The two manifest-level scripts are the repository's own, not a consumer's:
+`check-manifests.mjs` fails any package it cannot find in `PACKAGE_REGISTRY`, so
+pointing it at a generated workspace reports every app and shared package as
+unregistered. Layering for generated workspaces is not solved by running these
+scripts there.
+
+## Not yet implemented
+
+- No layer for the app side of a generated workspace: nothing stops
+  `apps/api` from importing `apps/admin` directly. §7.2 only describes the
+  framework's own graph.
+- The config takes no options beyond `tsconfigRootDir` — no way to relax one rule
+  for one project without copying the array. That is deliberate for now: the
+  first escape hatch is the one every project takes.
+- This package has no test suite of its own. Its behaviour is asserted from
+  outside, by `tools/boundaries/verify-enforcement.mjs` and by the repository
+  linting itself.

package/boundaries.js

@@ -0,0 +1,90 @@
+/**
+ * ESLint flat-config blocks that enforce the layered dependency rule
+ * (PLAN.md §7.2) at the **source** level.
+ *
+ * The companion manifest check (`tools/boundaries/check-manifests.mjs`) enforces
+ * the same rule at the **package.json** level, so a violation cannot slip
+ * through by being declared as a dependency but imported dynamically.
+ *
+ * Cross-package *relative* imports (`../../data/src/thing`) are caught by the
+ * compiler instead: every package sets `rootDir: src`, so reaching outside it is
+ * a typecheck error.
+ */
+
+import tseslint from 'typescript-eslint';
+
+import { PACKAGE_REGISTRY, forbiddenDependencies } from './layers.js';
+
+/** Packages that must stay free of any runtime/framework dependency. */
+const PURE_TYPE_PACKAGES = ['@nage-api/contracts'];
+
+/** Modules a types-only package may never pull in. */
+const RUNTIME_MODULES = ['@nestjs/*', '@nestjs/*/**', 'rxjs', 'rxjs/**', 'zod', 'zod/**'];
+
+/**
+ * @param {string} pkg
+ * @returns {string[]} minimatch patterns covering the package and its subpaths
+ */
+function importPatternsFor(pkg) {
+  return [pkg, `${pkg}/*`, `${pkg}/**`];
+}
+
+/**
+ * Build one ESLint config object per scaffolded package.
+ *
+ * @returns {import('eslint').Linter.Config[]}
+ */
+export function boundaryConfigs() {
+  /** @type {import('eslint').Linter.Config[]} */
+  const configs = [];
+
+  for (const [pkg, meta] of Object.entries(PACKAGE_REGISTRY)) {
+    const forbidden = forbiddenDependencies(pkg).flatMap(importPatternsFor);
+
+    /** @type {{ group: string[]; message: string }[]} */
+    const patterns = [];
+
+    if (forbidden.length > 0) {
+      patterns.push({
+        group: forbidden,
+        message:
+          `Dependency-direction violation (PLAN.md §7.2): "${pkg}" (layer: ${meta.layer}) ` +
+          `may not import this package. Depend downward only — collaborate through ` +
+          `@nage-api/contracts interfaces and @nage-api/core DI tokens instead.`,
+      });
+    }
+
+    if (PURE_TYPE_PACKAGES.includes(pkg)) {
+      patterns.push({
+        group: RUNTIME_MODULES,
+        message:
+          `"${pkg}" is a types-only package (PLAN.md §8): no runtime code, no Nest, ` +
+          `no validation libraries. Move the implementation to @nage-api/core or a feature package.`,
+      });
+    }
+
+    if (patterns.length === 0) continue;
+
+    // TypeScript sources use the typescript-eslint variant so that `import type`
+    // cannot be used to sidestep the rule.
+    configs.push({
+      name: `nage/boundaries/${pkg}`,
+      files: [`${meta.dir}/**/*.{ts,tsx,mts,cts}`],
+      plugins: { '@typescript-eslint': tseslint.plugin },
+      rules: {
+        '@typescript-eslint/no-restricted-imports': ['error', { patterns }],
+      },
+    });
+
+    // Tooling and config files inside a package are plain JS.
+    configs.push({
+      name: `nage/boundaries/${pkg}/js`,
+      files: [`${meta.dir}/**/*.{js,mjs,cjs}`],
+      rules: {
+        'no-restricted-imports': ['error', { patterns }],
+      },
+    });
+  }
+
+  return configs;
+}

package/index.js

@@ -0,0 +1,145 @@
+/**
+ * Shared strict ESLint flat config for the @nage-api monorepo.
+ *
+ * Implements PLAN.md §13 (Type-Safety Strategy):
+ *   - `no-explicit-any` is an error
+ *   - the `no-unsafe-*` family is an error (type-aware)
+ *   - `no-floating-promises` is an error
+ *   - `explicit-module-boundary-types` is an error for published source
+ * plus the layered dependency rules from §7.2 (see ./boundaries.js).
+ */
+
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+import prettier from 'eslint-config-prettier';
+
+import { boundaryConfigs } from './boundaries.js';
+
+export const IGNORES = [
+  '**/node_modules/**',
+  '**/dist/**',
+  '**/coverage/**',
+  '**/.turbo/**',
+  '**/*.tsbuildinfo',
+  // Generated by the docs example gate (tools/docs/check-examples.mjs), which
+  // typechecks it against the real API. Linting extracted snippets would enforce
+  // rules on prose the reader is meant to adapt, not on code we ship.
+  '**/.examples/**',
+  // Docusaurus build output.
+  '**/.docusaurus/**',
+];
+
+/**
+ * @param {{ tsconfigRootDir: string }} options
+ * @returns {import('eslint').Linter.Config[]}
+ */
+export function nageEslintConfig({ tsconfigRootDir }) {
+  return tseslint.config(
+    { name: 'nage/ignores', ignores: IGNORES },
+
+    // ── Type-aware baseline for all TypeScript sources ──────────────────────
+    {
+      name: 'nage/typescript',
+      files: ['**/*.{ts,mts,cts}'],
+      extends: [...tseslint.configs.strictTypeChecked, ...tseslint.configs.stylisticTypeChecked],
+      languageOptions: {
+        parserOptions: { projectService: true, tsconfigRootDir },
+        globals: { ...globals.node },
+      },
+      rules: {
+        '@typescript-eslint/no-explicit-any': 'error',
+        '@typescript-eslint/no-unsafe-argument': 'error',
+        '@typescript-eslint/no-unsafe-assignment': 'error',
+        '@typescript-eslint/no-unsafe-call': 'error',
+        '@typescript-eslint/no-unsafe-member-access': 'error',
+        '@typescript-eslint/no-unsafe-return': 'error',
+        '@typescript-eslint/no-floating-promises': 'error',
+        '@typescript-eslint/no-misused-promises': 'error',
+        '@typescript-eslint/consistent-type-imports': [
+          'error',
+          { prefer: 'type-imports', fixStyle: 'inline-type-imports' },
+        ],
+        '@typescript-eslint/consistent-type-exports': 'error',
+        '@typescript-eslint/no-unused-vars': [
+          'error',
+          { argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
+        ],
+        // Numbers in messages are unambiguous; objects and unions are not.
+        '@typescript-eslint/restrict-template-expressions': ['error', { allowNumber: true }],
+        'no-console': ['error', { allow: ['warn', 'error'] }],
+        eqeqeq: ['error', 'always', { null: 'ignore' }],
+        'prefer-const': 'error',
+        'no-restricted-syntax': [
+          'error',
+          {
+            selector: "MemberExpression[object.name='Math'][property.name='random']",
+            message:
+              'Math.random() is not cryptographically secure (PLAN.md §12). Use node:crypto (randomInt/randomBytes).',
+          },
+        ],
+      },
+    },
+
+    // ── Published package source: exported API must be explicitly typed ─────
+    {
+      name: 'nage/package-source',
+      files: ['packages/*/src/**/*.ts', 'packages/*/*/src/**/*.ts'],
+      rules: {
+        '@typescript-eslint/explicit-module-boundary-types': 'error',
+      },
+    },
+
+    // ── NestJS module classes ───────────────────────────────────────────────
+    // A `forRoot`-only module is the framework's own idiom, not a missing
+    // namespace: `@Module({})` needs a class to decorate.
+    {
+      name: 'nage/nest-modules',
+      files: ['**/*.module.ts'],
+      rules: {
+        '@typescript-eslint/no-extraneous-class': 'off',
+      },
+    },
+
+    // ── Tests: pragmatic relaxations ────────────────────────────────────────
+    // HTTP test clients (supertest) type their responses as `any`, test modules
+    // are legitimately empty classes, and referencing a method to identify a
+    // route handler is not a `this`-binding mistake. Production source keeps all
+    // of these as errors.
+    {
+      name: 'nage/tests',
+      files: ['**/test/**/*.ts', '**/*.spec.ts', '**/*.e2e-spec.ts'],
+      rules: {
+        '@typescript-eslint/explicit-module-boundary-types': 'off',
+        '@typescript-eslint/no-unsafe-assignment': 'off',
+        '@typescript-eslint/no-unsafe-argument': 'off',
+        '@typescript-eslint/no-unsafe-member-access': 'off',
+        '@typescript-eslint/no-non-null-assertion': 'off',
+        '@typescript-eslint/no-extraneous-class': 'off',
+        '@typescript-eslint/unbound-method': 'off',
+      },
+    },
+
+    // ── Tooling scripts and flat configs (plain JS, not type-aware) ─────────
+    {
+      name: 'nage/javascript',
+      files: ['**/*.{js,mjs,cjs}'],
+      extends: [tseslint.configs.disableTypeChecked],
+      languageOptions: {
+        ecmaVersion: 2023,
+        sourceType: 'module',
+        globals: { ...globals.node },
+      },
+      rules: {
+        'no-console': 'off',
+      },
+    },
+
+    // ── Dependency-direction enforcement (§7.2) ─────────────────────────────
+    ...boundaryConfigs(),
+
+    // Must stay last: turns off stylistic rules Prettier owns.
+    prettier,
+  );
+}
+
+export default nageEslintConfig;

package/layers.js

@@ -0,0 +1,179 @@
+/**
+ * Single source of truth for the layered dependency rule (PLAN.md §7.2).
+ *
+ *   apps
+ *     ▼
+ *   @nage-api/cli
+ *     ▼
+ *   drivers (@nage-api/data-sql, @nage-api/data-mongo)
+ *     ▼
+ *   feature packages (@nage-api/auth, @nage-api/data, @nage-api/config, …)
+ *     ▼
+ *   @nage-api/core
+ *     ▼
+ *   @nage-api/contracts  +  @nage-api/testing
+ *
+ * Rule: dependencies point **downward only**. Feature packages must not import
+ * each other — they collaborate through `@nage-api/contracts` interfaces and DI
+ * tokens exposed by `@nage-api/core`.
+ *
+ * Consumed by:
+ *   - `boundaries.js`      → ESLint `no-restricted-imports` rules (source level)
+ *   - `tools/boundaries/*` → package.json manifest checks (dependency level)
+ *
+ * Packages are registered here before they exist so that a new package cannot be
+ * added to the workspace without declaring which layer it belongs to.
+ */
+
+/** @typedef {'contracts' | 'core' | 'feature' | 'driver' | 'cli' | 'tooling'} Layer */
+
+/** Ordered from the bottom of the dependency graph upwards. */
+export const LAYER_ORDER = /** @type {const} */ (['contracts', 'core', 'feature', 'driver', 'cli']);
+
+/**
+ * Every package the framework owns, with its workspace directory and layer.
+ * `dir` is relative to the repository root and may be absent for packages that
+ * are planned but not yet scaffolded.
+ *
+ * @type {Record<string, { dir: string; layer: Layer; scaffolded: boolean }>}
+ */
+export const PACKAGE_REGISTRY = {
+  // ── layer: contracts ──────────────────────────────────────────────────────
+  '@nage-api/contracts': { dir: 'packages/contracts', layer: 'contracts', scaffolded: true },
+  '@nage-api/testing': { dir: 'packages/testing', layer: 'contracts', scaffolded: true },
+
+  // ── layer: core ───────────────────────────────────────────────────────────
+  '@nage-api/core': { dir: 'packages/core', layer: 'core', scaffolded: true },
+
+  // ── layer: feature ────────────────────────────────────────────────────────
+  '@nage-api/config': { dir: 'packages/config', layer: 'feature', scaffolded: true },
+  '@nage-api/data': { dir: 'packages/data', layer: 'feature', scaffolded: true },
+  '@nage-api/auth': { dir: 'packages/auth', layer: 'feature', scaffolded: true },
+  '@nage-api/cache': { dir: 'packages/cache', layer: 'feature', scaffolded: true },
+  '@nage-api/queue': { dir: 'packages/queue', layer: 'feature', scaffolded: true },
+  '@nage-api/storage': { dir: 'packages/storage', layer: 'feature', scaffolded: true },
+  '@nage-api/realtime': { dir: 'packages/realtime', layer: 'feature', scaffolded: true },
+  '@nage-api/notify': { dir: 'packages/notify', layer: 'feature', scaffolded: true },
+  '@nage-api/observability': {
+    dir: 'packages/observability',
+    layer: 'feature',
+    scaffolded: true,
+  },
+  '@nage-api/compat': { dir: 'packages/compat', layer: 'feature', scaffolded: true },
+  '@nage-api/integrations-email': {
+    dir: 'packages/integrations/email',
+    layer: 'feature',
+    scaffolded: false,
+  },
+  '@nage-api/integrations-sms': {
+    dir: 'packages/integrations/sms',
+    layer: 'feature',
+    scaffolded: false,
+  },
+  '@nage-api/integrations-firebase': {
+    dir: 'packages/integrations/firebase',
+    layer: 'feature',
+    scaffolded: false,
+  },
+  '@nage-api/integrations-stripe': {
+    dir: 'packages/integrations/stripe',
+    layer: 'feature',
+    scaffolded: false,
+  },
+  '@nage-api/integrations-square': {
+    dir: 'packages/integrations/square',
+    layer: 'feature',
+    scaffolded: false,
+  },
+  '@nage-api/integrations-recaptcha': {
+    dir: 'packages/integrations/recaptcha',
+    layer: 'feature',
+    scaffolded: true,
+  },
+  '@nage-api/integrations-geocoder': {
+    dir: 'packages/integrations/geocoder',
+    layer: 'feature',
+    scaffolded: false,
+  },
+
+  // ── layer: driver ─────────────────────────────────────────────────────────
+  '@nage-api/data-sql': { dir: 'packages/data/data-sql', layer: 'driver', scaffolded: true },
+  '@nage-api/data-mongo': {
+    dir: 'packages/data/data-mongo',
+    layer: 'driver',
+    scaffolded: false,
+  },
+
+  // ── layer: cli ────────────────────────────────────────────────────────────
+  '@nage-api/cli': { dir: 'packages/cli', layer: 'cli', scaffolded: true },
+
+  // ── tooling (build-time only; never a runtime dependency) ─────────────────
+  '@nage-api/eslint-config': {
+    dir: 'packages/eslint-config',
+    layer: 'tooling',
+    scaffolded: true,
+  },
+};
+
+/**
+ * Explicit, justified exceptions to the strict layer rule. Anything added here
+ * needs a comment saying why the generic rule does not fit.
+ *
+ * @type {Record<string, readonly string[]>}
+ */
+export const ALLOWED_EXCEPTIONS = {
+  // `@nage-api/testing` ships fixtures typed against the shared contracts.
+  '@nage-api/testing': ['@nage-api/contracts'],
+  // Drivers implement the ports declared by their base package.
+  '@nage-api/data-sql': ['@nage-api/data'],
+  '@nage-api/data-mongo': ['@nage-api/data'],
+};
+
+/** Packages every workspace package may depend on as a *dev* dependency. */
+export const TOOLING_PACKAGES = ['@nage-api/eslint-config', '@nage-api/testing'];
+
+/**
+ * Runtime dependencies `pkg` is allowed to declare/import.
+ *
+ * @param {string} pkg
+ * @returns {string[]}
+ */
+export function allowedDependencies(pkg) {
+  const entry = PACKAGE_REGISTRY[pkg];
+  if (entry === undefined) return [];
+
+  const exceptions = ALLOWED_EXCEPTIONS[pkg] ?? [];
+  if (entry.layer === 'tooling') return [...exceptions];
+
+  if (entry.layer === 'cli') {
+    // The CLI orchestrates the whole framework; it may depend on any package.
+    return Object.keys(PACKAGE_REGISTRY).filter((name) => name !== pkg);
+  }
+
+  const level = LAYER_ORDER.indexOf(entry.layer);
+  const lower = Object.entries(PACKAGE_REGISTRY)
+    .filter(([name, meta]) => {
+      if (name === pkg || meta.layer === 'tooling') return false;
+      const otherLevel = LAYER_ORDER.indexOf(meta.layer);
+      return otherLevel !== -1 && otherLevel < level;
+    })
+    .map(([name]) => name);
+
+  return [...new Set([...lower, ...exceptions])];
+}
+
+/**
+ * `@nage-api/*` packages `pkg` must never import.
+ *
+ * @param {string} pkg
+ * @returns {string[]}
+ */
+export function forbiddenDependencies(pkg) {
+  const allowed = new Set(allowedDependencies(pkg));
+  return Object.keys(PACKAGE_REGISTRY).filter((name) => name !== pkg && !allowed.has(name));
+}
+
+/** @returns {[string, { dir: string; layer: Layer; scaffolded: boolean }][]} */
+export function scaffoldedPackages() {
+  return Object.entries(PACKAGE_REGISTRY).filter(([, meta]) => meta.scaffolded);
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@nage-api/eslint-config",
+  "version": "1.0.0-beta.2",
+  "description": "Shared strict ESLint flat config + layered dependency-boundary rules for @nage-api packages",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./index.js",
+    "./layers": "./layers.js",
+    "./boundaries": "./boundaries.js"
+  },
+  "files": [
+    "index.js",
+    "layers.js",
+    "boundaries.js",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "eslint": ">=10.0.0"
+  },
+  "dependencies": {
+    "eslint-config-prettier": "10.1.8",
+    "globals": "17.11.0",
+    "typescript-eslint": "8.67.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {}
+}