@mettlecast/eslint-plugin-domain-module 0.2.60 → 0.2.62

package/README.md

@@ -34,8 +34,8 @@ export default [
 | `no-cross-domain-internal-import` | Importing internal modules (not exported types) from another domain directory | error |
 | `flow-domain-ownership` | Flow files in `domains/{x}/flows/` must declare `owningDomain: 'x'` | error |
 | `zod-defaults-required` | Top-level Zod input/output schemas must end in `.default(...)` | error |
-| `api-needs-fixture` | Every `defineApi` needs a sibling `__tests__/<id>.fixture.json` | error |
-| `prefer-result-over-throw` | Domain API handlers must `return err({...})` instead of throwing | error |
+| `api-needs-fixture` | Every API-exposed `defineAction` needs a sibling `__tests__/<id>.fixture.json` | error |
+| `prefer-result-over-throw` | Domain handlers must `return err({...})` instead of throwing | error |
 | `use-tanstack-router` | Frontend must use TanStack Router | error |
 | `tanstack-query-options` | TanStack Query data must be wrapped in `queryOptions(...)` | warn |
 
@@ -114,4 +114,4 @@ await ctx.db.release(); // only if you really need to release early
 ## See Also
 
 - `@mettlecast/domain-runtime` — handler definitions and `DomainContext`
-- `@mettlecast/domain-cli` — validation and linting
+- `@mettlecast/domain-cli` — validation and linting

package/dist/__tests__/api-needs-fixture.test.js

@@ -14,10 +14,10 @@ RuleTester.describe = describe;
 RuleTester.it = it;
 const existsSyncMock = vi.mocked(existsSync);
 const FIXTURE_DIRS_WITH_FIXTURE = new Set([
-    '/repo/domains/auth/api/__tests__/get-user.fixture.json',
+    '/repo/domains/auth/actions/__tests__/get-user.fixture.json',
 ]);
 const FIXTURE_DIRS_WITHOUT_FIXTURE = new Set([
-    '/repo/domains/payments/api/__tests__/charge-card.fixture.json',
+    '/repo/domains/payments/actions/__tests__/charge-card.fixture.json',
 ]);
 beforeEach(() => {
     existsSyncMock.mockReset();
@@ -39,22 +39,26 @@ const tester = new RuleTester({
 tester.run('api-needs-fixture', apiNeedsFixture, {
     valid: [
         {
-            filename: '/repo/domains/auth/api/get-user.ts',
-            code: "import { defineApi } from '@mettlecast/domain-runtime'; export const getUser = defineApi({ id: 'get-user', path: '/v1/users/{id}', method: 'GET', tenancy: 'required', versions: { v1: { status: 'stable', input: z.object({}), output: z.object({}), handler: async () => ({}) } } });",
+            filename: '/repo/domains/auth/actions/get-user.ts',
+            code: "import { defineAction } from '@mettlecast/domain-runtime'; export const getUser = defineAction({ id: 'get-user', backendAccess: 'domain', exposure: { type: 'api', path: '/v1/users/{id}', method: 'GET', auth: 'required', tenancy: 'required' }, idempotent: true, input: z.object({}), output: z.object({}), handler: async () => ({}) });",
         },
         {
             filename: '/repo/domains/auth/domain.config.ts',
             code: "export const config = { id: 'auth', name: 'Auth' };",
         },
         {
-            filename: '/repo/domains/auth/api/utils.ts',
+            filename: '/repo/domains/auth/actions/utils.ts',
             code: "export function helper() { return 1; }",
         },
+        {
+            filename: '/repo/domains/auth/actions/internal-helper.ts',
+            code: "import { defineAction } from '@mettlecast/domain-runtime'; export const helper = defineAction({ id: 'helper', backendAccess: 'private', exposure: { type: 'internal' }, idempotent: true, input: z.object({}), output: z.object({}), handler: async () => ({}) });",
+        },
     ],
     invalid: [
         {
-            filename: '/repo/domains/payments/api/charge-card.ts',
-            code: "import { defineApi } from '@mettlecast/domain-runtime'; export const chargeCard = defineApi({ id: 'charge-card', path: '/v1/charge', method: 'POST', tenancy: 'required', versions: { v1: { status: 'stable', input: z.object({}), output: z.object({}), handler: async () => ({}) } } });",
+            filename: '/repo/domains/payments/actions/charge-card.ts',
+            code: "import { defineAction } from '@mettlecast/domain-runtime'; export const chargeCard = defineAction({ id: 'charge-card', backendAccess: 'domain', exposure: { type: 'api', path: '/v1/charge', method: 'POST', auth: 'required', tenancy: 'required' }, idempotent: false, input: z.object({}), output: z.object({}), handler: async () => ({}) });",
             errors: [{ messageId: 'apiNeedsFixture' }],
         },
     ],

package/dist/__tests__/no-raw-fetch.test.js

@@ -10,26 +10,26 @@ const tester = new RuleTester({
 tester.run('no-raw-fetch', noRawFetch, {
     valid: [
         {
-            filename: '/repo/domains/auth/api/get-user.ts',
-            code: "export const get = defineApi({ handler: async (input, ctx) => { return await ctx.fetch('https://example.com'); } });",
+            filename: '/repo/domains/auth/actions/get-user.ts',
+            code: "export const get = defineAction({ handler: async (input, ctx) => { return await ctx.fetch('https://example.com'); } });",
         },
         {
-            filename: '/repo/domains/auth/api/get-user.ts',
+            filename: '/repo/domains/auth/actions/get-user.ts',
             code: "import ky from 'ky'; const r = await ky.get('https://example.com');",
         },
         {
-            filename: '/repo/domains/auth/api/get-user.ts',
+            filename: '/repo/domains/auth/actions/get-user.ts',
             code: "const r = await globalThis.fetch('https://example.com');",
         },
     ],
     invalid: [
         {
-            filename: '/repo/domains/auth/api/get-user.ts',
+            filename: '/repo/domains/auth/actions/get-user.ts',
             code: "const r = await fetch('https://example.com');",
             errors: [{ messageId: 'noRawFetch' }],
         },
         {
-            filename: '/repo/domains/payments/api/charge.ts',
+            filename: '/repo/domains/payments/actions/charge.ts',
             code: "fetch('https://api.stripe.com/v1/charges', { method: 'POST' });",
             errors: [{ messageId: 'noRawFetch' }],
         },

package/dist/__tests__/no-raw-http-server.test.js

@@ -9,7 +9,7 @@ const tester = new RuleTester({
 });
 tester.run('no-raw-http-server', noRawHttpServer, {
     valid: [
-        { code: "import { defineApi } from '@mettlecast/domain-runtime';" },
+        { code: "import { defineAction } from '@mettlecast/domain-runtime';" },
         { code: "import path from 'node:path';" },
     ],
     invalid: [

package/dist/__tests__/no-raw-pg-client.test.js

@@ -10,7 +10,7 @@ const tester = new RuleTester({
 tester.run('no-raw-pg-client', noRawPgClient, {
     valid: [
         // Domain code that uses ctx.db is fine.
-        { code: "import { defineApi } from '@mettlecast/domain-runtime';" },
+        { code: "import { defineAction } from '@mettlecast/domain-runtime';" },
         { code: "import { drizzle } from 'drizzle-orm/node-postgres';" },
         // Other packages that aren't in the ban-list stay allowed.
         { code: "import { something } from 'pg-query-emscripten';" },

package/dist/__tests__/prefer-result-over-throw.test.js

@@ -10,17 +10,17 @@ const ruleTester = new RuleTester({
 ruleTester.run('prefer-result-over-throw', preferResultOverThrow, {
     valid: [
         {
-            filename: 'domains/auth/api/me.ts',
+            filename: 'domains/auth/actions/me.ts',
             code: `
 import { ok, err } from '@mettlecast/domain-runtime';
-export const me = defineApi({
+export const me = defineAction({
   handler: async (_input, _ctx) => {
     return ok({ id: 'usr_1' });
   },
 });`,
         },
         {
-            filename: 'domains/auth/api/me.ts',
+            filename: 'domains/auth/actions/me.ts',
             code: `
 import { redirect } from '@tanstack/react-router';
 // TSR redirect is not a domain error — it's a navigation directive
@@ -31,10 +31,10 @@ throw redirect({ to: '/dashboard' });`,
             code: `throw new Error('Upgrade failed');`,
         },
         {
-            filename: 'domains/auth/api/me.ts',
+            filename: 'domains/auth/actions/me.ts',
             code: `
 import { ok, err, notFound } from '@mettlecast/domain-runtime';
-export const me = defineApi({
+export const me = defineAction({
   handler: async (_input, _ctx) => {
     const user = await ctx.db.query(...);
     if (!user) return notFound('user', input.userId);
@@ -45,9 +45,9 @@ export const me = defineApi({
     ],
     invalid: [
         {
-            filename: 'domains/auth/api/me.ts',
+            filename: 'domains/auth/actions/me.ts',
             code: `
-export const me = defineApi({
+export const me = defineAction({
   handler: async () => {
     throw new Error('User not found');
   },
@@ -55,9 +55,9 @@ export const me = defineApi({
             errors: [{ messageId: 'preferResult' }],
         },
         {
-            filename: 'domains/orgs/api/list-orgs.ts',
+            filename: 'domains/orgs/actions/list-orgs.ts',
             code: `
-export const listOrgs = defineApi({
+export const listOrgs = defineAction({
   handler: async (_input, _ctx) => {
     if (!ctx.tenant) throw new Error('Missing tenant');
     return { items: [] };
@@ -66,9 +66,9 @@ export const listOrgs = defineApi({
             errors: [{ messageId: 'preferResult' }],
         },
         {
-            filename: 'domains/tenants/api/create-tenant.ts',
+            filename: 'domains/tenants/actions/create-tenant.ts',
             code: `
-export const createTenant = defineApi({
+export const createTenant = defineAction({
   handler: async () => {
     throw { kind: 'not_found' }; // raw object throw — no stack trace
   },

package/dist/__tests__/require-define-primitive.test.js

@@ -9,7 +9,7 @@ const tester = new RuleTester({
 });
 tester.run('require-define-primitive', requireDefinePrimitive, {
     valid: [
-        { code: "export const myApi = defineApi({ id: 'test', path: '/test' });" },
+        { code: "export const myAction = defineAction({ id: 'test', exposure: { type: 'internal' } });" },
         { code: "export const sub = defineSubscriber({ id: 'x', event: 'y', semverRange: '^1.0' });" },
         { code: "const domain = defineDomain({ id: 'my-domain', name: 'My Domain', tenancy: 'single' });" },
     ],

package/dist/rules/api-needs-fixture.js

@@ -2,18 +2,9 @@ import { ESLintUtils } from '@typescript-eslint/utils';
 import { existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 const createRule = ESLintUtils.RuleCreator((name) => `https://github.com/LawrenceGeeHouse/Mettlecast/blob/develop/packages/eslint-plugin-domain-module/docs/${name}.md`);
-const DOMAIN_API_FILE_PATTERN = /[/\\]domains[/\\][^/\\]+[/\\]api[/\\][^/\\]+\.ts$/;
-function extractFixtureIdFromDefineApi(node) {
-    const arg = node.arguments[0];
-    if (!arg || arg.type !== 'ObjectExpression')
-        return undefined;
-    const idProp = arg.properties.find((p) => p.type === 'Property' &&
-        'name' in p.key &&
-        !p.computed &&
-        p.key.name === 'id');
-    if (!idProp)
-        return undefined;
-    const val = idProp.value;
+const DOMAIN_ACTION_FILE_PATTERN = /[/\\]domains[/\\][^/\\]+[/\\]actions[/\\][^/\\]+\.ts$/;
+function stringPropertyValue(prop) {
+    const val = prop.value;
     if (val.type === 'Literal' && typeof val.value === 'string')
         return val.value;
     if (val.type === 'TemplateLiteral' && val.expressions.length === 0 && val.quasis.length === 1) {
@@ -21,29 +12,50 @@ function extractFixtureIdFromDefineApi(node) {
     }
     return undefined;
 }
-function isDefineApiCall(node) {
+function findProperty(object, name) {
+    return object.properties.find((p) => p.type === 'Property' &&
+        'name' in p.key &&
+        !p.computed &&
+        p.key.name === name);
+}
+function extractFixtureIdFromApiAction(node) {
+    const arg = node.arguments[0];
+    if (!arg || arg.type !== 'ObjectExpression')
+        return undefined;
+    const exposureProp = findProperty(arg, 'exposure');
+    if (!exposureProp || exposureProp.value.type !== 'ObjectExpression')
+        return undefined;
+    const typeProp = findProperty(exposureProp.value, 'type');
+    if (!typeProp || stringPropertyValue(typeProp) !== 'api')
+        return undefined;
+    const idProp = findProperty(arg, 'id');
+    if (!idProp)
+        return undefined;
+    return stringPropertyValue(idProp);
+}
+function isDefineActionCall(node) {
     if (!node)
         return false;
-    return node.callee.type === 'Identifier' && node.callee.name === 'defineApi';
+    return node.callee.type === 'Identifier' && node.callee.name === 'defineAction';
 }
 export const apiNeedsFixture = createRule({
     name: 'api-needs-fixture',
     meta: {
         type: 'problem',
         docs: {
-            description: 'Every exported defineApi({...}) in domains/{x}/api/*.ts must have a matching __tests__/{id}.fixture.json sibling file.',
+            description: 'Every exported API-exposed defineAction({...}) in domains/{x}/actions/*.ts must have a matching __tests__/{id}.fixture.json sibling file.',
         },
         messages: {
-            apiNeedsFixture: 'API handler "{{name}}" is missing a __tests__/{{name}}.fixture.json sibling file.\n  fixHint: Create `domains/<domain>/api/__tests__/{{name}}.fixture.json` with realistic input/output examples. This file is consumed by `mc-domain-module test` to drive the handler in a local fixture run.\n  kNodeRef: K:runbook:fixture-driven-tests',
+            apiNeedsFixture: 'API-exposed action "{{name}}" is missing a __tests__/{{name}}.fixture.json sibling file.\n  fixHint: Create `domains/<domain>/actions/__tests__/{{name}}.fixture.json` with realistic input/output examples. This file is consumed by `mc-domain-module test` to drive the handler in a local fixture run.\n  kNodeRef: K:runbook:fixture-driven-tests',
         },
         schema: [],
     },
     defaultOptions: [],
     create(context) {
         const filename = context.filename ?? context.getFilename?.() ?? '';
-        if (!filename || !DOMAIN_API_FILE_PATTERN.test(filename))
+        if (!filename || !DOMAIN_ACTION_FILE_PATTERN.test(filename))
             return {};
-        const apiDir = dirname(filename);
+        const actionDir = dirname(filename);
         return {
             ExportNamedDeclaration(node) {
                 const decl = node.declaration;
@@ -52,7 +64,7 @@ export const apiNeedsFixture = createRule({
                 let callNode;
                 if (decl.type === 'VariableDeclaration') {
                     for (const d of decl.declarations) {
-                        if (d.init && d.init.type === 'CallExpression' && isDefineApiCall(d.init)) {
+                        if (d.init && d.init.type === 'CallExpression' && isDefineActionCall(d.init)) {
                             callNode = d.init;
                             break;
                         }
@@ -63,16 +75,16 @@ export const apiNeedsFixture = createRule({
                     // with a double-cast through unknown to avoid TS's
                     // "may be a mistake" error on discriminated unions.
                     const d = decl;
-                    if (d.type === 'CallExpression' && isDefineApiCall(decl)) {
+                    if (d.type === 'CallExpression' && isDefineActionCall(decl)) {
                         callNode = decl;
                     }
                 }
                 if (!callNode)
                     return;
-                const id = extractFixtureIdFromDefineApi(callNode);
+                const id = extractFixtureIdFromApiAction(callNode);
                 if (!id)
                     return;
-                const fixturePath = join(apiDir, '__tests__', `${id}.fixture.json`);
+                const fixturePath = join(actionDir, '__tests__', `${id}.fixture.json`);
                 if (!existsSync(fixturePath)) {
                     context.report({ node, messageId: 'apiNeedsFixture', data: { name: id } });
                 }

package/dist/rules/no-raw-http-server.js

@@ -9,7 +9,7 @@ export const noRawHttpServer = createRule({
             description: 'Disallow HTTP server framework imports (express, koa, fastify, aws-lambda) in domain files.',
         },
         messages: {
-            noRawHttpServer: 'HTTP framework import "{{source}}" is not allowed in domain files. The Domain Module runtime handles transport binding.\n  fixHint: Remove the `{{source}}` import. Domain primitives (defineApi, defineWebhook) are transport-agnostic — the runtime handles HTTP binding.\n  kNodeRef: K:convention:tier-1-foundations',
+            noRawHttpServer: 'HTTP framework import "{{source}}" is not allowed in domain files. The Domain Module runtime handles transport binding.\n  fixHint: Remove the `{{source}}` import. Domain primitives (defineAction, defineWebhook) are transport-agnostic — the runtime handles HTTP binding.\n  kNodeRef: K:convention:tier-1-foundations',
         },
         schema: [],
     },

package/dist/rules/require-define-primitive.js

@@ -1,7 +1,7 @@
 import { ESLintUtils } from '@typescript-eslint/utils';
 const createRule = ESLintUtils.RuleCreator((name) => `https://github.com/LawrenceGeeHouse/Mettlecast/blob/develop/packages/eslint-plugin-domain-module/docs/${name}.md`);
 const DEFINE_CALLS = new Set([
-    'defineApi', 'defineWebhook', 'defineSubscriber', 'defineSchedule',
+    'defineWebhook', 'defineSubscriber', 'defineSchedule',
     'defineJob', 'defineAction', 'defineIntegration', 'defineEvent', 'defineDomain', 'defineFlow',
 ]);
 export const requireDefinePrimitive = createRule({
@@ -12,7 +12,7 @@ export const requireDefinePrimitive = createRule({
             description: 'Domain primitive files must export at least one define*() call result.',
         },
         messages: {
-            missingDefinePrimitive: 'No define*() call found in this domain primitive file. Export at least one defineApi(), defineWebhook(), defineSubscriber(), etc.\n  fixHint: Wrap the file\'s export in a define*() call (e.g., `export const handler = defineApi({...})`). See domain.config.ts for the list of available primitives.\n  kNodeRef: K:runbook:add-domain',
+            missingDefinePrimitive: 'No define*() call found in this domain primitive file. Export at least one defineAction(), defineWebhook(), defineSubscriber(), etc.\n  fixHint: Wrap the file\'s export in a define*() call (e.g., `export const handler = defineAction({...})`). See domain.config.ts for the list of available primitives.\n  kNodeRef: K:runbook:add-domain',
         },
         schema: [],
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mettlecast/eslint-plugin-domain-module",
-  "version": "0.2.60",
+  "version": "0.2.62",
   "type": "module",
   "files": [
     "dist"