domain-driver 0.4.0 → 0.5.0

package/README.md

@@ -23,12 +23,12 @@ npx domain-driver make:feature <feature>[/<Entity>]
 Every command reads your `package.json` once and prints the stack it found before writing anything:
 
 ```
-Stack: next-fullstack (detected)
+Stack: next-fullstack (detected), root: src/app
 ```
 
 | Stack | Detected when | Features live in |
 |---|---|---|
-| `nest` | `@nestjs/core` is a dependency | `src/<feature>` |
+| `nest` | `@nestjs/core` is a dependency | `src/features/<feature>` if `src/features` exists, otherwise `src/<feature>` |
 | `tanstack-start` | `@tanstack/react-start` is a dependency | `src/routes/<feature>` or `routes/<feature>` |
 | `next-fullstack` | `next` is a dependency and `app/api`, `src/app/api`, `pages/api`, or `src/pages/api` exists | `app/<feature>` or `src/app/<feature>` |
 | `next-frontend` | `next` is a dependency, no api directory | `app/<feature>` or `src/app/<feature>` |
@@ -43,6 +43,34 @@ Override detection with `--stack`:
 domain-driver --stack nest make:feature cat -a
 ```
 
+### Choosing where features live
+
+The "Features live in" column is a convention, not a rule. Two overrides take precedence over it, in this order.
+
+`--root` wins over everything, and suits one-off scaffolding:
+
+```bash
+domain-driver --root src/modules make:feature billing/Billing -a
+```
+
+For a project you work in daily, set it once in `package.json` instead of retyping the flag on every command:
+
+```json
+{
+  "domainDriver": {
+    "featureRoot": "src/modules"
+  }
+}
+```
+
+Either way the stack line tells you which one won, so you can see where files will land before they land:
+
+```
+Stack: nest (detected), root: src/modules (package.json)
+```
+
+The root must be a relative path inside the project. An absolute path or one containing `..` is rejected rather than quietly normalised.
+
 ---
 
 ## What each stack generates
@@ -238,6 +266,49 @@ Every layer directory carries a `-` prefix so TanStack Router excludes it from r
 
 ---
 
+## Nest module registration
+
+On NestJS, generated classes are wired into the module files that have to know about them. `make:feature` adds the feature module to your root module, and `make:controller`, `make:service`, `make:repository` and `make:action` add their classes to `<feature>.module.ts`.
+
+```
+✅ Registered AssetsModule in src/app.module.ts
+```
+
+The edit is made through the TypeScript compiler API, borrowed from your own project rather than bundled, and applied as a text insertion at AST-computed positions. Your comments, import order and formatting survive untouched — only the two inserted lines are new. Registering the same class twice does nothing.
+
+A bespoke action's controller is inserted **before** `Show<Entity>Controller` rather than appended, because Nest matches routes in declaration order and a custom `GET /actives` would otherwise be swallowed by `GET /:id`.
+
+### When it does not edit
+
+If the root module cannot be found, TypeScript cannot be resolved, the file has no `@Module` decorator, or the edited result would not parse, nothing is written and the lines are printed for you to paste:
+
+```
+ℹ️  Did not edit src/app.module.ts (no @Module decorator with an object argument was found). Add by hand:
+     import { AssetsModule } from './features/assets/assets.module';
+     imports: [ ..., AssetsModule ]
+```
+
+The command still succeeds, because the files it generated were still generated.
+
+### Turning it off, and pointing it somewhere else
+
+```bash
+domain-driver --no-auto-register make:feature assets/Asset -a
+```
+
+```json
+{
+  "domainDriver": {
+    "autoRegister": false,
+    "rootModule": "src/core/root.module.ts"
+  }
+}
+```
+
+`autoRegister: false` restores the old behaviour, where nothing but newly generated files is ever written. `rootModule` names the root module for projects where `src/app.module.ts` and `app.module.ts` are both wrong.
+
+---
+
 ## Philosophy
 
 Everything for a feature lives in one folder, and every file does one thing.
@@ -277,11 +348,33 @@ The cache lives in `~/.cache/domain-driver` (or `$XDG_CACHE_HOME/domain-driver`)
 
 ---
 
+## Upgrading from 0.4.x
+
+On NestJS, scaffolding now **edits two files it did not create**: your root module and each feature's module. Every earlier version only ever created files. The edit is surgical and verified — see [Nest module registration](#nest-module-registration) for what it does and when it refuses — but if you want the old write-only guarantee back:
+
+```json
+{ "domainDriver": { "autoRegister": false } }
+```
+
+Nothing changes for any other stack.
+
+---
+
+## Upgrading from 0.4.0
+
+Two changes affect existing projects.
+
+On NestJS, a project that already has a `src/features` directory now scaffolds into it instead of directly into `src`. If you keep features in `src` you are unaffected, since the behaviour is opt-in by that directory existing. To pin either choice explicitly, set `domainDriver.featureRoot` in `package.json`.
+
+The entity half of a `<feature>/<Entity>` target must now be PascalCase. `make:schema users/user` previously produced `Listuser.service.ts` exporting `ListuserService`; it now fails with a message telling you to pass `User`.
+
+---
+
 ## Upgrading from 0.3.x
 
 Hooks are now one file per action — `<Action><Entity>.hook.ts` exporting `use<Action><Entity>` (`useListCat`, `useCreateCat`, ...) — instead of a single combined `use<Entity>.ts`, which is no longer generated. `make:hook` now takes `<feature>/<Entity>`, not `<feature>/use<Entity>`. `make:action` writes a matching hook alongside the service and repository on any stack that has a hook layer.
 
-domain-driver never overwrites a file that already exists, so this only changes new scaffolding: a `use<Entity>.ts` written by an older version is left alone and keeps working. New features and new actions get the per-action hooks; wire them together in the container, since they no longer share state:
+domain-driver never overwrites a generated file that already exists, so this only changes new scaffolding: a `use<Entity>.ts` written by an older version is left alone and keeps working. New features and new actions get the per-action hooks; wire them together in the container, since they no longer share state:
 
 ```tsx
 const { data, loading, error, refetch } = useListCat();

package/dist/cli.js

@@ -43,7 +43,8 @@ const component_1 = require("./commands/component");
 const container_1 = require("./commands/container");
 const controller_1 = require("./commands/controller");
 const feature_1 = require("./commands/feature");
-const hints_1 = require("./commands/hints");
+const register_1 = require("./commands/register");
+const resolve_1 = require("./commands/resolve");
 const hook_1 = require("./commands/hook");
 const repository_1 = require("./commands/repository");
 const schema_1 = require("./commands/schema");
@@ -78,7 +79,9 @@ function createProgram(deps) {
         .name('domain-driver')
         .description('CLI scaffolding tool for domain-driven feature folders in Next.js, React, Node, and NestJS projects')
         .version(deps.current)
-        .option('--stack <name>', `Override stack detection (${types_2.STACK_NAMES.join(', ')})`);
+        .option('--stack <name>', `Override stack detection (${types_2.STACK_NAMES.join(', ')})`)
+        .option('--root <dir>', 'Override where feature folders are created, for example src/features')
+        .option('--no-auto-register', 'Do not edit Nest module files; print what to add instead');
     let pendingNotice = Promise.resolve(null);
     program.hook('preAction', (_thisCommand, actionCommand) => {
         const name = actionCommand.name();
@@ -93,8 +96,12 @@ function createProgram(deps) {
         }
         if (SKIP_DETECTION.has(name))
             return;
-        const { stack } = program.opts();
-        deps.log((0, detect_1.describeStack)((0, detect_1.detectStack)(stack)));
+        const { stack, root } = program.opts();
+        // commander defaults a --no-x flag to true, which would shadow the package.json key,
+        // so only an explicitly passed flag counts as an override.
+        const passed = program.getOptionValueSource('autoRegister') === 'cli';
+        const autoRegister = passed ? program.opts().autoRegister : undefined;
+        deps.log((0, detect_1.describeStack)((0, detect_1.detectStack)({ stack, root, autoRegister })));
     });
     program.hook('postAction', async () => {
         const notice = await pendingNotice;
@@ -139,7 +146,7 @@ function createProgram(deps) {
         const { feature, name } = (0, target_1.parseTarget)(target);
         const wrote = (0, service_1.makeService)(feature, name, (0, sides_1.parseSide)(options.side));
         if (wrote)
-            (0, hints_1.hintRegisterInModule)(feature, (0, hints_1.standardClassNames)(name, 'Service'));
+            (0, register_1.registerClasses)((0, resolve_1.requireFeature)(feature), 'service', (0, register_1.standardActionNames)(name));
     });
     program
         .command('make:repository <target>')
@@ -149,7 +156,7 @@ function createProgram(deps) {
         const { feature, name } = (0, target_1.parseTarget)(target);
         const wrote = (0, repository_1.makeRepository)(feature, name, (0, sides_1.parseSide)(options.side));
         if (wrote)
-            (0, hints_1.hintRegisterInModule)(feature, (0, hints_1.standardClassNames)(name, 'Repository'));
+            (0, register_1.registerClasses)((0, resolve_1.requireFeature)(feature), 'repository', (0, register_1.standardActionNames)(name));
     });
     program
         .command('make:controller <target>')
@@ -158,7 +165,7 @@ function createProgram(deps) {
         const { feature, name } = (0, target_1.parseTarget)(target);
         const wrote = (0, controller_1.makeController)(feature, name);
         if (wrote)
-            (0, hints_1.hintRegisterInModule)(feature, (0, hints_1.standardClassNames)(name, 'Controller'));
+            (0, register_1.registerClasses)((0, resolve_1.requireFeature)(feature), 'controller', (0, register_1.standardActionNames)(name));
     });
     program
         .command('make:action <target> <action>')
@@ -171,7 +178,7 @@ function createProgram(deps) {
         const wrote = (0, action_1.makeAction)(feature, name, action, { withInput: options.withInput, returns });
         if (wrote) {
             const { pascal } = (0, actions_1.actionCase)(action);
-            (0, hints_1.hintRegisterInModule)(feature, [`${pascal}Controller`, `${pascal}Service`, `${pascal}Repository`], `list ${pascal}Controller before Show${name}Controller in controllers`);
+            (0, register_1.registerCustomAction)((0, resolve_1.requireFeature)(feature), pascal, name);
         }
     });
     program

package/dist/commands/feature.js

@@ -46,6 +46,7 @@ const container_1 = require("./container");
 const controller_1 = require("./controller");
 const hook_1 = require("./hook");
 const repository_1 = require("./repository");
+const register_1 = require("./register");
 const resolve_1 = require("./resolve");
 const schema_1 = require("./schema");
 const service_1 = require("./service");
@@ -61,6 +62,7 @@ async function makeFeature(name, all = false, entityName) {
     if (all)
         scaffoldLayers(ctx, entity);
     writeEntryFile(ctx, entity, all);
+    (0, register_1.registerFeatureModule)(ctx, entity);
     if (all)
         console.log(`✅ All files scaffolded for "${name}"`);
 }

package/dist/commands/hints.js

@@ -3,10 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.resetHints = resetHints;
 exports.hintNestjsZod = hintNestjsZod;
 exports.hintReactQuery = hintReactQuery;
-exports.standardClassNames = standardClassNames;
-exports.hintRegisterInModule = hintRegisterInModule;
-const detect_1 = require("../stack/detect");
-const actions_1 = require("../templates/actions");
 let nestjsZodHinted = false;
 let reactQueryHinted = false;
 function resetHints() {
@@ -27,12 +23,3 @@ function hintReactQuery(profile) {
     console.log('ℹ️  Hooks use TanStack Query. Install it: npm install @tanstack/react-query');
     console.log('   Then wrap your app in a QueryClientProvider.');
 }
-function standardClassNames(name, suffix) {
-    return actions_1.ACTIONS.map((action) => `${action}${name}${suffix}`);
-}
-function hintRegisterInModule(feature, classNames, note) {
-    if ((0, detect_1.detectStack)().stack !== 'nest')
-        return;
-    const suffix = note !== undefined ? ` (${note})` : '';
-    console.log(`ℹ️  Register ${classNames.join(', ')} in ${feature}.module.ts${suffix}`);
-}

package/dist/commands/register.js

@@ -0,0 +1,105 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KINDS = void 0;
+exports.registerClasses = registerClasses;
+exports.standardActionNames = standardActionNames;
+exports.registerCustomAction = registerCustomAction;
+exports.registerFeatureModule = registerFeatureModule;
+const path = __importStar(require("path"));
+const registration_1 = require("../nest/registration");
+const root_module_1 = require("../nest/root-module");
+const registry_1 = require("../stack/registry");
+const actions_1 = require("../templates/actions");
+const fs_1 = require("../utils/fs");
+exports.KINDS = Object.freeze({
+    controller: { layer: 'controller', suffix: 'Controller', fileSuffix: 'controller', property: 'controllers' },
+    service: { layer: 'serverService', suffix: 'Service', fileSuffix: 'service', property: 'providers' },
+    repository: { layer: 'serverRepository', suffix: 'Repository', fileSuffix: 'repository', property: 'providers' },
+});
+function featureModule(ctx) {
+    return path.join(ctx.featureDir, `${ctx.feature}.module.ts`);
+}
+function entriesFor(ctx, kind, names) {
+    const dir = path.join(ctx.featureDir, (0, registry_1.layerDir)(ctx.profile, kind.layer));
+    return names
+        .map((name) => ({
+        identifier: `${name}${kind.suffix}`,
+        definedIn: path.join(dir, `${name}.${kind.fileSuffix}.ts`),
+        property: kind.property,
+    }))
+        .filter((entry) => (0, fs_1.fileExists)(entry.definedIn));
+}
+/** Registers generated classes in the feature's own module. Nest is the only stack with one. */
+function registerClasses(ctx, kind, actionNames) {
+    if (ctx.profile.name !== 'nest')
+        return;
+    (0, registration_1.applyRegistrations)(featureModule(ctx), entriesFor(ctx, exports.KINDS[kind], actionNames), ctx.stack.autoRegister);
+}
+function standardActionNames(entity) {
+    return actions_1.ACTIONS.map((action) => `${action}${entity}`);
+}
+/**
+ * A bespoke action's controller must be declared ahead of Show<Entity>Controller: Nest matches
+ * routes in declaration order, and a custom GET path would otherwise be swallowed by `/:id`.
+ */
+function registerCustomAction(ctx, action, entity) {
+    if (ctx.profile.name !== 'nest')
+        return;
+    const entries = [
+        { ...entriesFor(ctx, exports.KINDS.controller, [action])[0], before: `Show${entity}Controller` },
+        entriesFor(ctx, exports.KINDS.service, [action])[0],
+        entriesFor(ctx, exports.KINDS.repository, [action])[0],
+    ];
+    (0, registration_1.applyRegistrations)(featureModule(ctx), entries, ctx.stack.autoRegister);
+}
+/** Registers the feature's module in the application's root module. */
+function registerFeatureModule(ctx, entity) {
+    if (ctx.profile.name !== 'nest')
+        return;
+    const moduleFile = featureModule(ctx);
+    if (!(0, fs_1.fileExists)(moduleFile))
+        return;
+    const rootModule = (0, root_module_1.findRootModule)(process.cwd(), ctx.stack.featureRoot, ctx.stack.rootModule);
+    if (rootModule === null) {
+        if (!ctx.stack.autoRegister)
+            return;
+        console.log(`ℹ️  No root module found, so ${entity}Module was not registered. Add it by hand, or name the file with "domainDriver": { "rootModule": "..." } in package.json.`);
+        return;
+    }
+    if (path.resolve(rootModule) === path.resolve(moduleFile))
+        return;
+    (0, registration_1.applyRegistrations)(rootModule, [{ identifier: `${entity}Module`, definedIn: moduleFile, property: 'imports' }], ctx.stack.autoRegister);
+}

package/dist/commands/target.js

@@ -3,11 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseTarget = parseTarget;
 exports.parseFeatureTarget = parseFeatureTarget;
 const naming_1 = require("../utils/naming");
-const NAME_PATTERN = /^[A-Za-z][A-Za-z0-9]*$/;
+const NAME_PATTERN = /^[A-Z][A-Za-z0-9]*$/;
+const HOOK_NAME_PATTERN = /^use[A-Z]/;
 function validateName(name) {
-    if (!NAME_PATTERN.test(name)) {
-        throw new Error(`Name "${name}" must be letters and digits only, for example User.`);
+    if (NAME_PATTERN.test(name))
+        return;
+    if (HOOK_NAME_PATTERN.test(name)) {
+        throw new Error(`Name "${name}" is a hook name. Pass the entity instead, for example ${name.slice(3)}.`);
     }
+    throw new Error(`Name "${name}" must be PascalCase, for example User.`);
 }
 function parseTarget(value) {
     const parts = value.split('/');

package/dist/init/content.js

@@ -35,7 +35,9 @@ const SKILL_LINES = [
     '',
     '## Detect the stack',
     '',
-    'The tool reads `package.json` and prints `Stack: <stack> (detected)` before every command. Stacks: `next-fullstack`, `next-frontend`, `react`, `node` (Express, Fastify, Hono, or none), `nest`, `tanstack-start`. Override with `--stack <name>` if detection is wrong.',
+    'The tool reads `package.json` and prints `Stack: <stack> (detected), root: <dir>` before every command. Stacks: `next-fullstack`, `next-frontend`, `react`, `node` (Express, Fastify, Hono, or none), `nest`, `tanstack-start`. Override with `--stack <name>` if detection is wrong.',
+    'Where features are written can be overridden too: `--root <dir>` for one command, or a `domainDriver.featureRoot` key in `package.json` for the project. Read the root off the stack line rather than assuming the convention.',
+    'On Nest the tool registers what it generates: the feature module in the root module, and controllers, services and repositories in `<feature>.module.ts`. Do not add those by hand — it prints what it registered, and prints the lines to paste when it cannot. A bespoke action controller is placed before `Show<Entity>Controller` so its route is not swallowed by `/:id`.',
     '',
     '## Commands',
     '',
@@ -70,7 +72,7 @@ const SKILL_LINES = [
     '',
     '- Next.js: `app/<feature>` or `src/app/<feature>`; route handlers under `app/api/<feature>`.',
     '- React and Node: `src/features/<feature>` or `features/<feature>`.',
-    '- Nest: `src/<feature>` with a `<feature>.module.ts`.',
+    '- Nest: `src/features/<feature>` when `src/features` exists, otherwise `src/<feature>`, with a `<feature>.module.ts`.',
     '- TanStack Start: `src/routes/<feature>` or `routes/<feature>`; every layer folder is prefixed with `-` so the router ignores it, and the entry file is `index.tsx`, not `page.tsx`.',
 ];
 exports.AGENTS_SECTION = AGENTS_LINES.join('\n');

package/dist/nest/register.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerInModule = registerInModule;
+function bail(reason) {
+    return { status: 'bailed', reason };
+}
+function parse(ts, source) {
+    return ts.createSourceFile('module.ts', source, ts.ScriptTarget.Latest, true);
+}
+function moduleArgument(ts, file) {
+    for (const statement of file.statements) {
+        if (!ts.isClassDeclaration(statement) || !ts.canHaveDecorators(statement))
+            continue;
+        for (const decorator of ts.getDecorators(statement) ?? []) {
+            const call = decorator.expression;
+            if (!ts.isCallExpression(call))
+                continue;
+            if (!ts.isIdentifier(call.expression) || call.expression.text !== 'Module')
+                continue;
+            const [argument] = call.arguments;
+            if (argument !== undefined && ts.isObjectLiteralExpression(argument))
+                return argument;
+        }
+    }
+    return null;
+}
+function propertyArray(ts, object, name) {
+    for (const property of object.properties) {
+        if (!ts.isPropertyAssignment(property))
+            continue;
+        const key = property.name;
+        const text = ts.isIdentifier(key) || ts.isStringLiteral(key) ? key.text : null;
+        if (text !== name)
+            continue;
+        return ts.isArrayLiteralExpression(property.initializer) ? property.initializer : 'not-array';
+    }
+    return 'missing';
+}
+function contains(ts, array, identifier) {
+    return array.elements.some((element) => ts.isIdentifier(element) && element.text === identifier);
+}
+function newlineOf(source) {
+    return source.includes('\r\n') ? '\r\n' : '\n';
+}
+function alreadyImported(ts, file, identifier) {
+    return file.statements.filter(ts.isImportDeclaration).some((declaration) => {
+        const bindings = declaration.importClause?.namedBindings;
+        if (bindings === undefined || !ts.isNamedImports(bindings))
+            return false;
+        return bindings.elements.some((element) => element.name.text === identifier);
+    });
+}
+function indentAt(source, position) {
+    const lineStart = source.lastIndexOf('\n', position - 1) + 1;
+    return /^[ \t]*/.exec(source.slice(lineStart, position))?.[0] ?? '';
+}
+function importEdit(ts, source, file, request) {
+    // A second `import { X }` for an identifier already bound is a duplicate declaration, which
+    // is a type error rather than a syntax error, so nothing downstream would catch it.
+    if (alreadyImported(ts, file, request.identifier))
+        return null;
+    const eol = newlineOf(source);
+    const line = `import { ${request.identifier} } from '${request.importPath}';`;
+    const imports = file.statements.filter(ts.isImportDeclaration);
+    if (imports.length === 0)
+        return { at: 0, text: `${line}${eol}` };
+    return { at: imports[imports.length - 1].end, text: `${eol}${line}` };
+}
+function elementEdit(ts, source, file, array, request) {
+    const identifier = request.identifier;
+    const eol = newlineOf(source);
+    if (array.elements.length === 0) {
+        const outer = indentAt(source, array.getStart(file));
+        return { at: array.end - 1, text: `${eol}${outer}  ${identifier},${eol}${outer}` };
+    }
+    const anchor = request.before === undefined
+        ? undefined
+        : array.elements.find((element) => ts.isIdentifier(element) && element.text === request.before);
+    const last = array.elements[array.elements.length - 1];
+    const singleLine = !source.slice(array.getStart(file), last.end).includes('\n');
+    if (anchor !== undefined) {
+        const at = anchor.getStart(file);
+        return { at, text: singleLine ? `${identifier}, ` : `${identifier},${eol}${indentAt(source, at)}` };
+    }
+    const text = singleLine ? `, ${identifier}` : `,${eol}${indentAt(source, last.getStart(file))}${identifier}`;
+    return { at: last.end, text };
+}
+function apply(source, edits) {
+    return [...edits]
+        .sort((a, b) => b.at - a.at)
+        .reduce((text, edit) => `${text.slice(0, edit.at)}${edit.text}${text.slice(edit.at)}`, source);
+}
+/**
+ * The edit is only returned if the result both parses cleanly and reads back as registered.
+ * A wrong offset produces a file that fails one of those, and the caller keeps the original.
+ */
+function parses(ts, source) {
+    const diagnostics = ts.transpileModule(source, {
+        reportDiagnostics: true,
+        compilerOptions: { target: ts.ScriptTarget.Latest },
+    }).diagnostics;
+    return (diagnostics ?? []).length === 0;
+}
+function verify(ts, source, request) {
+    if (!parses(ts, source))
+        return false;
+    const file = parse(ts, source);
+    const object = moduleArgument(ts, file);
+    if (object === null)
+        return false;
+    const array = propertyArray(ts, object, request.property);
+    if (array === 'missing' || array === 'not-array')
+        return false;
+    return contains(ts, array, request.identifier);
+}
+function registerInModule(ts, source, request) {
+    if (!parses(ts, source))
+        return bail('the file does not parse');
+    const file = parse(ts, source);
+    const object = moduleArgument(ts, file);
+    if (object === null)
+        return bail('no @Module decorator with an object argument was found');
+    const array = propertyArray(ts, object, request.property);
+    if (array === 'missing')
+        return bail(`the @Module decorator has no "${request.property}" property`);
+    if (array === 'not-array')
+        return bail(`"${request.property}" is not an array literal`);
+    if (contains(ts, array, request.identifier))
+        return { status: 'already-registered' };
+    const edits = [importEdit(ts, source, file, request), elementEdit(ts, source, file, array, request)];
+    const edited = apply(source, edits.filter((edit) => edit !== null));
+    if (!verify(ts, edited, request))
+        return bail('the edited file did not read back as valid');
+    return { status: 'edited', source: edited };
+}

package/dist/nest/registration.js

@@ -0,0 +1,129 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyRegistrations = applyRegistrations;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const imports_1 = require("../utils/imports");
+const register_1 = require("./register");
+const typescript_1 = require("./typescript");
+/**
+ * Edits one module file in place, or explains what to add by hand and changes nothing.
+ * A bail is never a failure: the generated files exist either way, so the caller succeeds.
+ */
+function applyRegistrations(moduleFile, entries, enabled) {
+    if (entries.length === 0)
+        return;
+    if (!enabled)
+        return explain(moduleFile, entries, 'automatic registration is off');
+    if (!fs.existsSync(moduleFile))
+        return explain(moduleFile, entries, 'the module file does not exist');
+    const ts = (0, typescript_1.loadTypeScript)(process.cwd());
+    if (ts === null)
+        return explain(moduleFile, entries, 'typescript could not be resolved from this project');
+    let source;
+    try {
+        source = fs.readFileSync(moduleFile, 'utf-8');
+    }
+    catch {
+        return explain(moduleFile, entries, 'the file could not be read');
+    }
+    const added = [];
+    const outstanding = [];
+    for (const entry of entries) {
+        const result = (0, register_1.registerInModule)(ts, source, {
+            identifier: entry.identifier,
+            importPath: (0, imports_1.resolveImport)(moduleFile, entry.definedIn),
+            property: entry.property,
+            before: entry.before,
+        });
+        if (result.status === 'bailed') {
+            return explain(moduleFile, [...outstanding, ...entries.slice(entries.indexOf(entry))], result.reason);
+        }
+        if (result.status === 'already-registered')
+            continue;
+        source = result.source;
+        added.push(entry.identifier);
+    }
+    if (added.length === 0)
+        return;
+    if (!write(moduleFile, source))
+        return explain(moduleFile, entries, 'the file could not be written');
+    console.log(`✅ Registered ${added.join(', ')} in ${relative(moduleFile)}`);
+}
+/**
+ * Writes through a sibling temp file and renames. `writeFileSync` truncates before writing, so a
+ * failure partway through would leave the file that boots the application cut in half.
+ * A same-directory rename is atomic, which makes that outcome unreachable.
+ */
+function write(moduleFile, source) {
+    const temporary = `${moduleFile}.domain-driver.tmp`;
+    try {
+        fs.writeFileSync(temporary, source);
+        fs.renameSync(temporary, moduleFile);
+        return true;
+    }
+    catch {
+        try {
+            fs.rmSync(temporary, { force: true });
+        }
+        catch {
+            // The temp file is already gone, or unremovable for the same reason the write failed.
+        }
+        return false;
+    }
+}
+function explain(moduleFile, entries, reason) {
+    if (entries.length === 0)
+        return;
+    console.log(`ℹ️  Did not edit ${relative(moduleFile)} (${reason}). Add by hand:`);
+    for (const entry of entries) {
+        console.log(`     import { ${entry.identifier} } from '${(0, imports_1.resolveImport)(moduleFile, entry.definedIn)}';`);
+    }
+    const byProperty = new Map();
+    for (const entry of entries) {
+        byProperty.set(entry.property, [...(byProperty.get(entry.property) ?? []), entry]);
+    }
+    for (const [property, group] of byProperty) {
+        console.log(`     ${property}: [ ..., ${group.map(placement).join(', ')} ]`);
+    }
+}
+/** An ordered entry has to say where it goes, or the pasted line reproduces the bug it prevents. */
+function placement(entry) {
+    return entry.before === undefined ? entry.identifier : `${entry.identifier}, ${entry.before}`;
+}
+function relative(target) {
+    return path.relative(process.cwd(), target) || target;
+}

package/dist/nest/root-module.js

@@ -0,0 +1,57 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findRootModule = findRootModule;
+const path = __importStar(require("path"));
+const fs_1 = require("../utils/fs");
+/**
+ * Probes the conventional locations for a Nest root module. A project that keeps it
+ * anywhere else names it with the `domainDriver.rootModule` key instead of being guessed at.
+ */
+function findRootModule(cwd, featureRoot, configured) {
+    if (configured !== null) {
+        const target = path.join(cwd, configured);
+        return (0, fs_1.fileExists)(target) ? target : null;
+    }
+    // Most specific first: a monorepo's stray root-level src/app.module.ts must not win over
+    // the one sitting beside the feature root it actually belongs to.
+    const candidates = [path.join(path.dirname(featureRoot), 'app.module.ts'), 'src/app.module.ts', 'app.module.ts'];
+    for (const candidate of candidates) {
+        const target = path.join(cwd, candidate);
+        if ((0, fs_1.fileExists)(target))
+            return target;
+    }
+    return null;
+}

package/dist/nest/typescript.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadTypeScript = loadTypeScript;
+/**
+ * Borrows the consuming project's own TypeScript rather than shipping one. Every TypeScript
+ * Nest project has it — it cannot compile without one — so this keeps a scaffolding CLI free
+ * of a heavy runtime dependency. Returning null is a normal outcome, not an error: the caller
+ * falls back to printing the lines for the user to paste.
+ */
+function loadTypeScript(cwd, resolve = require.resolve, load = require) {
+    try {
+        const candidate = load(resolve('typescript', { paths: [cwd] }));
+        return isTypeScript(candidate) ? candidate : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isTypeScript(candidate) {
+    if (typeof candidate !== 'object' || candidate === null)
+        return false;
+    const api = candidate;
+    return (typeof api.createSourceFile === 'function' &&
+        typeof api.transpileModule === 'function' &&
+        typeof api.getDecorators === 'function' &&
+        typeof api.canHaveDecorators === 'function');
+}

package/dist/stack/detect.js

@@ -41,41 +41,53 @@ const path = __importStar(require("path"));
 const fs_1 = require("../utils/fs");
 const types_1 = require("./types");
 const API_DIRS = ['app/api', 'src/app/api', 'pages/api', 'src/pages/api'];
+const ROOT_LABELS = Object.freeze({
+    detected: '',
+    flag: ' (--root)',
+    config: ' (package.json)',
+});
 let cached;
 function resetStackCache() {
     cached = undefined;
 }
-function detectStack(override) {
+function detectStack(options = {}) {
     if (cached)
         return cached;
     const cwd = process.cwd();
+    const override = options.stack;
     const overridden = override !== undefined;
-    const deps = readDependencies(cwd, overridden);
+    const pkg = readPackageJson(cwd, overridden);
+    const deps = dependencyNames(pkg);
     const stack = overridden ? parseOverride(override) : inferStack(cwd, deps);
+    const root = resolveRoot(cwd, stack, pkg, options.root);
     const result = Object.freeze({
         stack,
         source: overridden ? 'override' : 'detected',
         httpFramework: stack === 'node' ? detectHttpFramework(deps) : null,
-        featureRoot: resolveFeatureRoot(cwd, stack),
+        featureRoot: root.featureRoot,
+        featureRootSource: root.source,
         hasNestjsZod: deps.has('nestjs-zod'),
+        rootModule: configuredRootModule(pkg),
+        autoRegister: options.autoRegister ?? configuredAutoRegister(pkg),
     });
     cached = result;
     return result;
 }
 function describeStack(stack) {
     const base = `Stack: ${stack.stack} (${stack.source})`;
-    if (stack.stack !== 'node')
-        return base;
-    return `${base}, http: ${stack.httpFramework ?? 'none'}`;
+    const http = stack.stack === 'node' ? `, http: ${stack.httpFramework ?? 'none'}` : '';
+    return `${base}${http}, root: ${stack.featureRoot}${ROOT_LABELS[stack.featureRootSource]}`;
 }
-function readDependencies(cwd, optional) {
+function readPackageJson(cwd, optional) {
     const pkgPath = path.join(cwd, 'package.json');
     if (!fs.existsSync(pkgPath)) {
         if (optional)
-            return new Set();
+            return {};
         throw new Error(`No package.json found in ${cwd}. Run domain-driver from your project root, or pass --stack <name>.`);
     }
-    const pkg = parsePackageJson(pkgPath);
+    return parsePackageJson(pkgPath);
+}
+function dependencyNames(pkg) {
     return new Set([
         ...Object.keys(pkg.dependencies ?? {}),
         ...Object.keys(pkg.devDependencies ?? {}),
@@ -113,7 +125,56 @@ function hasApiDir(cwd) {
 function detectHttpFramework(deps) {
     return types_1.HTTP_FRAMEWORKS.find((name) => deps.has(name)) ?? null;
 }
-function resolveFeatureRoot(cwd, stack) {
+function resolveRoot(cwd, stack, pkg, flag) {
+    if (flag !== undefined) {
+        return { featureRoot: validateRoot(flag, '--root'), source: 'flag' };
+    }
+    const configured = configuredRoot(pkg);
+    if (configured !== null) {
+        return { featureRoot: configured, source: 'config' };
+    }
+    return { featureRoot: conventionalRoot(cwd, stack), source: 'detected' };
+}
+function configuredRootModule(pkg) {
+    const value = pkg.domainDriver?.rootModule;
+    if (value === undefined)
+        return null;
+    if (typeof value !== 'string') {
+        throw new Error('package.json "domainDriver.rootModule" must be a string, for example "src/app.module.ts".');
+    }
+    return validateRoot(value, 'package.json');
+}
+function configuredAutoRegister(pkg) {
+    const value = pkg.domainDriver?.autoRegister;
+    if (value === undefined)
+        return true;
+    if (typeof value !== 'boolean') {
+        throw new Error('package.json "domainDriver.autoRegister" must be true or false.');
+    }
+    return value;
+}
+function configuredRoot(pkg) {
+    const value = pkg.domainDriver?.featureRoot;
+    if (value === undefined)
+        return null;
+    if (typeof value !== 'string') {
+        throw new Error('package.json "domainDriver.featureRoot" must be a string, for example "src/features".');
+    }
+    return validateRoot(value, 'package.json');
+}
+/**
+ * The root becomes a filesystem path under the project, so an absolute path or any
+ * `..` segment would write outside it. Both are rejected rather than normalised away.
+ */
+function validateRoot(value, source) {
+    const normalized = value.replace(/\\/g, '/').replace(/\/+$/, '');
+    const escapes = normalized === '' || path.isAbsolute(value) || normalized.split('/').includes('..');
+    if (escapes) {
+        throw new Error(`Feature root "${value}" from ${source} must be a relative path inside the project, for example src/features.`);
+    }
+    return normalized;
+}
+function conventionalRoot(cwd, stack) {
     switch (stack) {
         case 'next-fullstack':
         case 'next-frontend':
@@ -122,7 +183,7 @@ function resolveFeatureRoot(cwd, stack) {
         case 'node':
             return (0, fs_1.isDirectory)(path.join(cwd, 'src')) ? 'src/features' : 'features';
         case 'nest':
-            return 'src';
+            return (0, fs_1.isDirectory)(path.join(cwd, 'src', 'features')) ? 'src/features' : 'src';
         case 'tanstack-start':
             if ((0, fs_1.isDirectory)(path.join(cwd, 'src', 'routes')))
                 return 'src/routes';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "domain-driver",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "CLI scaffolding tool for domain-driven feature folders in Next.js, React, Node, NestJS, and TanStack Start projects, with per-action files, bespoke actions, and agent guidance",
   "main": "dist/index.js",
   "bin": {