@ftisindia/create-app 0.1.1 → 0.1.3

package/README.md

@@ -92,3 +92,68 @@ add a module and the architecture rules.
 Released under the **PolyForm Noncommercial License 1.0.0** — free for any noncommercial
 use. **Commercial use requires a separate commercial license from
 [ftisindia.com](https://ftisindia.com).** See the bundled `LICENSE` file.
+
+## Generating a module with `gen:module`
+
+Every project this CLI generates ships a `gen:module` script. In any generated project,
+run it to scaffold a new feature module that already follows the project's auth, RBAC,
+request-context, and audit conventions.
+
+```bash
+npm run gen:module -- billing
+```
+
+> Note the `--` before the name — it tells npm to pass the argument through to the
+> generator. Names are normalized automatically, so `billing`, `Billing`,
+> `"invoice items"`, and `invoiceItems` all resolve to the same module.
+
+### What it generates
+
+For a name like `billing`, you get:
+
+- `src/modules/billing/billing.module.ts` — the NestJS module (wires controller + service)
+- `src/modules/billing/dto/billing-echo.dto.ts` — a sample DTO (class-validator + Swagger)
+- `src/modules/billing/application/services/billing.service.ts` — a service with
+  `getStatus()` and `echo()` that use Prisma, request context, and write an audit-log row
+- `src/modules/billing/presentation/billing.controller.ts` — an org-scoped controller
+  guarded by `JwtAuthGuard`, `OrgScopeGuard`, and `PermissionGuard`, exposing:
+  - `GET /organisations/:orgId/billing/status` — requires `billing.read`
+  - `POST /organisations/:orgId/billing/echo` — requires `billing.update`
+- `test/billing.spec.ts` — a starter unit test
+
+It also keeps RBAC in sync automatically by appending to:
+
+- `src/modules/access-control/types/permission-key.ts` — adds `billing.read` and `billing.update`
+- `src/modules/access-control/types/route-permission-registry.ts` — adds the two route
+  entries (startup and tests fail if a guarded route is missing here)
+
+The generator never overwrites existing files — it stops if any target already exists.
+
+### Two steps to finish
+
+1. **Register the module** in `src/app.module.ts` (the generator prints this reminder):
+   ```ts
+   import { BillingModule } from './modules/billing/billing.module';
+   // add BillingModule to the @Module({ imports: [...] }) array
+   ```
+2. **Re-seed permissions** so the new keys exist in the database and can be granted to roles:
+   ```bash
+   npm run prisma:seed
+   ```
+   Then assign `billing.read` / `billing.update` to the appropriate role(s).
+
+Start the app and the new guarded endpoints are live (visible in Swagger at `/docs`).
+
+### When not to use it
+
+- **You need a non-org-scoped or public route.** The output is hard-wired to
+  `/organisations/:orgId/<name>` with the org guards. Build global/unauthenticated
+  endpoints by hand instead.
+- **You're extending an existing module.** It scaffolds a brand-new module and refuses
+  to overwrite — add files to the existing module manually.
+- **Your feature doesn't map to simple read/update permissions.** It generates exactly
+  `<name>.read` and `<name>.update`; for richer permission sets, edit the generated
+  `permission-key.ts` and registry entries afterward.
+- **You want a different shape than the `status` + `echo` reference endpoints.** Treat
+  the output as a starting point, or copy `src/modules/sample` (see
+  `docs/SAMPLE_MODULE.md`) for a fuller reference.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ftisindia/create-app",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "One-command scaffolder for the Phase 1 NestJS foundation starter.",
   "type": "module",
   "bin": {

package/template/README.md

@@ -144,3 +144,67 @@ Swagger is mounted at `/docs` and includes tags, request schemas, response DTOs,
 common error responses, bearer authorization, route parameters, and examples for
 all implemented API routes. See `docs/API_REFERENCE.md` before adding or changing
 controllers.
+
+## Generating a module with `gen:module`
+
+Scaffold a new feature module that already follows the project's auth, RBAC,
+request-context, and audit conventions.
+
+```bash
+npm run gen:module -- billing
+```
+
+> Note the `--` before the name — it tells npm to pass the argument through to the
+> generator. Names are normalized automatically, so `billing`, `Billing`,
+> `"invoice items"`, and `invoiceItems` all resolve to the same module.
+
+### What it generates
+
+For a name like `billing`, you get:
+
+- `src/modules/billing/billing.module.ts` — the NestJS module (wires controller + service)
+- `src/modules/billing/dto/billing-echo.dto.ts` — a sample DTO (class-validator + Swagger)
+- `src/modules/billing/application/services/billing.service.ts` — a service with
+  `getStatus()` and `echo()` that use Prisma, request context, and write an audit-log row
+- `src/modules/billing/presentation/billing.controller.ts` — an org-scoped controller
+  guarded by `JwtAuthGuard`, `OrgScopeGuard`, and `PermissionGuard`, exposing:
+  - `GET /organisations/:orgId/billing/status` — requires `billing.read`
+  - `POST /organisations/:orgId/billing/echo` — requires `billing.update`
+- `test/billing.spec.ts` — a starter unit test
+
+It also keeps RBAC in sync automatically by appending to:
+
+- `src/modules/access-control/types/permission-key.ts` — adds `billing.read` and `billing.update`
+- `src/modules/access-control/types/route-permission-registry.ts` — adds the two route
+  entries (startup and tests fail if a guarded route is missing here)
+
+The generator never overwrites existing files — it stops if any target already exists.
+
+### Two steps to finish
+
+1. **Register the module** in `src/app.module.ts` (the generator prints this reminder):
+   ```ts
+   import { BillingModule } from './modules/billing/billing.module';
+   // add BillingModule to the @Module({ imports: [...] }) array
+   ```
+2. **Re-seed permissions** so the new keys exist in the database and can be granted to roles:
+   ```bash
+   npm run prisma:seed
+   ```
+   Then assign `billing.read` / `billing.update` to the appropriate role(s).
+
+Start the app and the new guarded endpoints are live (visible in Swagger at `/docs`).
+
+### When not to use it
+
+- **You need a non-org-scoped or public route.** The output is hard-wired to
+  `/organisations/:orgId/<name>` with the org guards. Build global/unauthenticated
+  endpoints by hand instead.
+- **You're extending an existing module.** It scaffolds a brand-new module and refuses
+  to overwrite — add files to the existing module manually.
+- **Your feature doesn't map to simple read/update permissions.** It generates exactly
+  `<name>.read` and `<name>.update`; for richer permission sets, edit the generated
+  `permission-key.ts` and registry entries afterward.
+- **You want a different shape than the `status` + `echo` reference endpoints.** Treat
+  the output as a starting point, or copy `src/modules/sample` (see
+  `docs/SAMPLE_MODULE.md`) for a fuller reference.

package/template/tsconfig.json

@@ -6,6 +6,7 @@
     "emitDecoratorMetadata": true,
     "experimentalDecorators": true,
     "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
     "target": "ES2023",
     "sourceMap": true,
     "outDir": "./dist",