@ftisindia/create-app 0.1.5 → 0.2.0

package/template/src/modules/reports/reports.module.ts

@@ -0,0 +1,335 @@
+import { Module } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { DiscoveryModule } from '@nestjs/core';
+import {
+  createInMemoryResultCache,
+  ReportActionService,
+  ReportDefinitionService,
+  ReportExportService,
+  ReportQueryService,
+  ReportRowActionRegistry,
+  ReportSourceRegistry,
+  ReportTagService,
+  ReportViewService,
+  SourceProviderRegistry,
+  type ResultCache,
+} from '@ftisindia/report-builder';
+import { AuthModule } from '../auth/auth.module';
+import { ReportsActionsService } from './application/services/reports-actions.service';
+import { ReportsDefinitionsService } from './application/services/reports-definitions.service';
+import { ReportsExportsService } from './application/services/reports-exports.service';
+import { ReportsExportDispatcherService } from './application/services/reports-export-dispatcher.service';
+import { ReportsQueriesService } from './application/services/reports-queries.service';
+import { ReportsSettingsReader } from './application/services/reports-settings-reader.service';
+import { ReportsViewsService } from './application/services/reports-views.service';
+import { CaslReportsAuthorization } from './infrastructure/casl-reports-authorization';
+import { PrismaReportsAuditSink } from './infrastructure/audit-sink.adapter';
+import { ReportsPrismaTxRunner } from './infrastructure/prisma-tx-runner';
+import { PrismaQueryExecutor } from './infrastructure/prisma-query-executor';
+import { PrismaSnapshotRunner } from './infrastructure/prisma-snapshot-runner';
+import { PrismaReportsCatalog } from './infrastructure/prisma-catalog.adapter';
+import { ReportsJobQueueNoop } from './infrastructure/reports-job-queue.adapter';
+import { LocalDiskReportExportStorage } from './infrastructure/storage/local-disk-export-storage.adapter';
+import { RequestReportsContext } from './infrastructure/request-reports-context';
+import { ReportsRegistryBootstrapService } from './infrastructure/registry/registry-bootstrap.service';
+import { ReportsSchemaCheckService } from './infrastructure/schema-check/reports-schema-check.service';
+import {
+  PrismaBulkActionRunStore,
+  PrismaExportJobStore,
+  PrismaReportDefinitionStore,
+  PrismaRowTagStore,
+  PrismaSavedViewStore,
+} from './infrastructure/stores';
+import { ReportsActionsController } from './presentation/reports-actions.controller';
+import { ReportsDefinitionsController } from './presentation/reports-definitions.controller';
+import { ReportsExportController } from './presentation/reports-export.controller';
+import { ReportsExportJobsController } from './presentation/reports-export-jobs.controller';
+import { ReportsQueryController } from './presentation/reports-query.controller';
+import { ReportsViewsController } from './presentation/reports-views.controller';
+import { OrgMembersReportSource } from './sources/org-members.source';
+import { REPORTS_RESULT_CACHE, REPORTS_TOKEN_SECRET } from './reports.tokens';
+
+/**
+ * The reports glue module — binds the framework-free @ftisindia/report-builder
+ * engine to this app's services (request context, CASL RBAC, AuditService,
+ * Prisma) and ships reports-OWNED async-export infrastructure (its own worker
+ * over ReportExportJob + org-scoped file storage). It imports NO FormsModule:
+ * form-backed sources and the delegated grid verbs live in the optional
+ * ReportsFormsModule bridge (§3.2 standalone guarantee). Engine services are
+ * composed here via factories over the adapters and stores; app extensions
+ * register through the @ReportSource/@ReportRowAction decorators.
+ *
+ * The engine core knows nothing about the form builder (the standalone
+ * guarantee, report design §3.2); the forms adapter wired below is what makes
+ * `kind: "form"` sources exist in THIS app.
+ */
+@Module({
+  imports: [AuthModule, DiscoveryModule],
+  controllers: [
+    // Listed before the definitions controller so the literal 'exports'
+    // segment wins over the ':key' parameter on the shared base path.
+    ReportsExportJobsController,
+    ReportsDefinitionsController,
+    ReportsQueryController,
+    ReportsViewsController,
+    ReportsActionsController,
+    ReportsExportController,
+  ],
+  providers: [
+    // Adapters over the ecosystem seams.
+    RequestReportsContext,
+    CaslReportsAuthorization,
+    PrismaReportsAuditSink,
+    ReportsPrismaTxRunner,
+    PrismaQueryExecutor,
+    PrismaSnapshotRunner,
+    PrismaReportsCatalog,
+    // Reports-OWNED async-export infrastructure — no forms outbox / UploadedFile.
+    ReportsJobQueueNoop,
+    LocalDiskReportExportStorage,
+    ReportsExportDispatcherService,
+    // Prisma store implementations of the engine ports.
+    PrismaReportDefinitionStore,
+    PrismaSavedViewStore,
+    PrismaExportJobStore,
+    PrismaBulkActionRunStore,
+    PrismaRowTagStore,
+    ReportsSettingsReader,
+    // Engine registries — singletons; extensions land via the bootstrap scan.
+    { provide: ReportSourceRegistry, useFactory: () => new ReportSourceRegistry() },
+    { provide: SourceProviderRegistry, useFactory: () => new SourceProviderRegistry() },
+    { provide: ReportRowActionRegistry, useFactory: () => new ReportRowActionRegistry() },
+    // Result cache (§5.7) — in-memory by default; rebind the token for Redis.
+    { provide: REPORTS_RESULT_CACHE, useFactory: () => createInMemoryResultCache() },
+    // HMAC key bytes for cursors and action tokens (resolved in reports.config).
+    {
+      provide: REPORTS_TOKEN_SECRET,
+      useFactory: (config: ConfigService) => {
+        const secret = config.get<Uint8Array>('reports.tokenSecret');
+        if (secret === undefined || secret.length === 0) {
+          throw new Error('reports.tokenSecret failed to resolve — check reports.config.ts.');
+        }
+        return secret;
+      },
+      inject: [ConfigService],
+    },
+    // Engine orchestration services, composed over the seams above.
+    {
+      provide: ReportDefinitionService,
+      useFactory: (
+        store: PrismaReportDefinitionStore,
+        providers: SourceProviderRegistry,
+        rowActions: ReportRowActionRegistry,
+        authz: CaslReportsAuthorization,
+        audit: PrismaReportsAuditSink,
+        txRunner: ReportsPrismaTxRunner,
+        catalog: PrismaReportsCatalog,
+        executor: PrismaQueryExecutor,
+        settings: ReportsSettingsReader,
+        secret: Uint8Array,
+      ) =>
+        new ReportDefinitionService({
+          store,
+          providers,
+          rowActions,
+          authz,
+          audit,
+          txRunner,
+          catalog,
+          executor,
+          policyFor: (orgId) => settings.policyFor(orgId),
+          secret,
+        }),
+      inject: [
+        PrismaReportDefinitionStore,
+        SourceProviderRegistry,
+        ReportRowActionRegistry,
+        CaslReportsAuthorization,
+        PrismaReportsAuditSink,
+        ReportsPrismaTxRunner,
+        PrismaReportsCatalog,
+        PrismaQueryExecutor,
+        ReportsSettingsReader,
+        REPORTS_TOKEN_SECRET,
+      ],
+    },
+    {
+      provide: ReportQueryService,
+      useFactory: (
+        store: PrismaReportDefinitionStore,
+        providers: SourceProviderRegistry,
+        rowActions: ReportRowActionRegistry,
+        tags: PrismaRowTagStore,
+        executor: PrismaQueryExecutor,
+        authz: CaslReportsAuthorization,
+        cache: ResultCache,
+        settings: ReportsSettingsReader,
+        secret: Uint8Array,
+      ) =>
+        new ReportQueryService({
+          store,
+          providers,
+          rowActions,
+          tags,
+          executor,
+          authz,
+          cache,
+          policyFor: (orgId) => settings.policyFor(orgId),
+          secret,
+        }),
+      inject: [
+        PrismaReportDefinitionStore,
+        SourceProviderRegistry,
+        ReportRowActionRegistry,
+        PrismaRowTagStore,
+        PrismaQueryExecutor,
+        CaslReportsAuthorization,
+        REPORTS_RESULT_CACHE,
+        ReportsSettingsReader,
+        REPORTS_TOKEN_SECRET,
+      ],
+    },
+    {
+      provide: ReportViewService,
+      useFactory: (
+        views: PrismaSavedViewStore,
+        definitions: PrismaReportDefinitionStore,
+        authz: CaslReportsAuthorization,
+        audit: PrismaReportsAuditSink,
+        txRunner: ReportsPrismaTxRunner,
+      ) => new ReportViewService({ views, definitions, authz, audit, txRunner }),
+      inject: [
+        PrismaSavedViewStore,
+        PrismaReportDefinitionStore,
+        CaslReportsAuthorization,
+        PrismaReportsAuditSink,
+        ReportsPrismaTxRunner,
+      ],
+    },
+    {
+      provide: ReportTagService,
+      useFactory: (
+        tags: PrismaRowTagStore,
+        authz: CaslReportsAuthorization,
+        audit: PrismaReportsAuditSink,
+        settings: ReportsSettingsReader,
+      ) =>
+        new ReportTagService({
+          tags,
+          authz,
+          audit,
+          policyFor: (orgId) => settings.policyFor(orgId),
+        }),
+      inject: [
+        PrismaRowTagStore,
+        CaslReportsAuthorization,
+        PrismaReportsAuditSink,
+        ReportsSettingsReader,
+      ],
+    },
+    {
+      provide: ReportActionService,
+      useFactory: (
+        definitions: PrismaReportDefinitionStore,
+        providers: SourceProviderRegistry,
+        actions: ReportRowActionRegistry,
+        runs: PrismaBulkActionRunStore,
+        executor: PrismaQueryExecutor,
+        authz: CaslReportsAuthorization,
+        audit: PrismaReportsAuditSink,
+        txRunner: ReportsPrismaTxRunner,
+        cache: ResultCache,
+        settings: ReportsSettingsReader,
+        secret: Uint8Array,
+      ) =>
+        new ReportActionService({
+          definitions,
+          providers,
+          actions,
+          runs,
+          executor,
+          authz,
+          audit,
+          txRunner,
+          cache,
+          policyFor: (orgId) => settings.policyFor(orgId),
+          secret,
+          // Glue row actions are Nest providers with their own injection —
+          // the engine's service-locator seam stays empty in this app.
+          services: {},
+        }),
+      inject: [
+        PrismaReportDefinitionStore,
+        SourceProviderRegistry,
+        ReportRowActionRegistry,
+        PrismaBulkActionRunStore,
+        PrismaQueryExecutor,
+        CaslReportsAuthorization,
+        PrismaReportsAuditSink,
+        ReportsPrismaTxRunner,
+        REPORTS_RESULT_CACHE,
+        ReportsSettingsReader,
+        REPORTS_TOKEN_SECRET,
+      ],
+    },
+    {
+      provide: ReportExportService,
+      useFactory: (
+        definitions: PrismaReportDefinitionStore,
+        providers: SourceProviderRegistry,
+        jobs: PrismaExportJobStore,
+        queue: ReportsJobQueueNoop,
+        sink: LocalDiskReportExportStorage,
+        snapshot: PrismaSnapshotRunner,
+        executor: PrismaQueryExecutor,
+        authz: CaslReportsAuthorization,
+        audit: PrismaReportsAuditSink,
+        txRunner: ReportsPrismaTxRunner,
+        settings: ReportsSettingsReader,
+        secret: Uint8Array,
+      ) =>
+        new ReportExportService({
+          definitions,
+          providers,
+          jobs,
+          queue,
+          sink,
+          snapshot,
+          executor,
+          authz,
+          audit,
+          txRunner,
+          policyFor: (orgId) => settings.policyFor(orgId),
+          secret,
+        }),
+      inject: [
+        PrismaReportDefinitionStore,
+        SourceProviderRegistry,
+        PrismaExportJobStore,
+        ReportsJobQueueNoop,
+        LocalDiskReportExportStorage,
+        PrismaSnapshotRunner,
+        PrismaQueryExecutor,
+        CaslReportsAuthorization,
+        PrismaReportsAuditSink,
+        ReportsPrismaTxRunner,
+        ReportsSettingsReader,
+        REPORTS_TOKEN_SECRET,
+      ],
+    },
+    // The example custom source (form-backed sources + delegated form verbs
+    // live in the optional ReportsFormsModule, not here — §3.2 standalone).
+    OrgMembersReportSource,
+    // Startup wiring + background work.
+    ReportsRegistryBootstrapService,
+    ReportsSchemaCheckService,
+    // Thin HTTP-facing services.
+    ReportsDefinitionsService,
+    ReportsQueriesService,
+    ReportsViewsService,
+    ReportsActionsService,
+    ReportsExportsService,
+  ],
+  exports: [ReportSourceRegistry, SourceProviderRegistry, ReportRowActionRegistry],
+})
+export class ReportsModule {}

package/template/src/modules/reports/reports.tokens.ts

@@ -0,0 +1,11 @@
+/**
+ * DI tokens for swappable reports seams. The defaults are bound in
+ * reports.module.ts; apps override them with custom providers (e.g. a
+ * Redis-backed ResultCache) without touching the module internals.
+ */
+
+/** Binds the engine's ResultCache port (report design §5.7). */
+export const REPORTS_RESULT_CACHE = Symbol('REPORTS_RESULT_CACHE');
+
+/** Key bytes for cursor/action-token HMACs (report design §5.3/§6.3). */
+export const REPORTS_TOKEN_SECRET = Symbol('REPORTS_TOKEN_SECRET');

package/template/src/modules/reports/sources/org-members.source.ts

@@ -0,0 +1,112 @@
+import { Injectable } from '@nestjs/common';
+import type { ReportSourceDef, SourceManifest, SourceQuery } from '@ftisindia/report-builder';
+import { ReportSource } from '../infrastructure/registry/report-extension.decorators';
+
+/**
+ * `kind: "custom"` example source (report design §3.2) over the template's own
+ * Membership/User/Role tables — the Phase-1 milestone proof (§14): a complete
+ * report with NO form-builder involvement, demonstrating the standalone
+ * guarantee before form integration exists.
+ *
+ * The contract split (§3): this class declares STRUCTURE only — the compiler
+ * owns query construction. It never sees a QuerySpec, so it cannot be injected
+ * and cannot bypass the allowlist.
+ *
+ * Nullability is read off prisma/schema.prisma, not assumed: User.displayName
+ * and User.email are nullable (String?), so their sortable columns are
+ * COALESCE-wrapped to '' and declared nullable: false — NULL poisons keyset
+ * predicates (§5.3). Role.name and the Membership columns are NOT NULL.
+ *
+ * Index specs are honest documentation (§5.2): they name the indexes an app
+ * WOULD create to publish this source on the indexed tier (org-leading btrees
+ * are impossible for User-side columns — User carries no orgId — so those
+ * specs live on "User" without the org prefix). The shipped example report
+ * runs on the LIVE tier, where the catalog lint does not require them.
+ */
+@Injectable()
+@ReportSource()
+export class OrgMembersReportSource implements ReportSourceDef {
+  readonly key = 'org-members';
+
+  manifest(): SourceManifest {
+    return {
+      // Membership id — the stable row identity tags and actions bind to (§7).
+      rowId: 'm."id"',
+      orgScoped: true,
+      columns: [
+        {
+          id: 'displayName',
+          sql: `COALESCE(u."displayName", '')`,
+          type: 'text',
+          sortable: true,
+          filterable: true,
+          searchable: true,
+          search: { mode: 'trgm' },
+          nullable: false,
+          collation: 'C',
+          index: {
+            name: 'idx_rb_member_display',
+            kind: 'btree',
+            table: 'User',
+            expr: `COALESCE("displayName", '') COLLATE "C"`,
+          },
+          // A btree cannot carry gin_trgm_ops — search gets its own index.
+          searchIndex: {
+            name: 'idx_rb_member_display_trgm',
+            kind: 'gin',
+            table: 'User',
+            expr: `COALESCE("displayName", '') gin_trgm_ops`,
+          },
+        },
+        {
+          id: 'email',
+          // User.email is String? in schema.prisma — surrogate '' keeps the
+          // sort key non-null (§5.3).
+          sql: `COALESCE(u."email", '')`,
+          type: 'text',
+          sortable: true,
+          filterable: true,
+          nullable: false,
+          collation: 'C',
+        },
+        {
+          id: 'role',
+          sql: 'r."name"',
+          type: 'text',
+          sortable: true,
+          filterable: true,
+          nullable: false,
+          collation: 'C',
+        },
+        {
+          id: 'status',
+          // MembershipStatus enum → text for binds and projection.
+          sql: 'm."status"::text',
+          type: 'enum',
+          filterable: true,
+          nullable: false,
+        },
+        {
+          id: 'joinedAt',
+          sql: 'm."createdAt"',
+          type: 'datetime',
+          valueKind: 'native',
+          sortable: true,
+          nullable: false,
+        },
+      ],
+    };
+  }
+
+  /** FROM/JOIN only — WHERE/ORDER/LIMIT belong to the compiler (§3). */
+  baseQuery(): SourceQuery {
+    return {
+      from:
+        '"Membership" m' +
+        ' JOIN "User" u ON u."id" = m."userId"' +
+        ' JOIN "Role" r ON r."id" = m."roleId"',
+      orgColumn: 'm."orgId"',
+      primaryTable: 'Membership',
+    };
+  }
+}

package/template/src/modules/settings/types/setting-definitions.ts

@@ -35,6 +35,66 @@ export const settingDefinitions = {
     defaultValue: '',
     parse: parseOptionalUrl,
   },
+  // Form builder (@ftisindia/form-builder) — org-variable policy lives here so
+  // it is typed, validated, and audited like every other org setting.
+  'forms.allowedDangerousActions': {
+    defaultValue: [],
+    parse: parseStringArray('forms.allowedDangerousActions', 50),
+  },
+  'forms.maxFileSizeMb': {
+    defaultValue: 10,
+    parse: parsePositiveInt('forms.maxFileSizeMb', 1024),
+  },
+  'forms.enableRuleIteration': {
+    defaultValue: false,
+    parse: parseBoolean,
+  },
+  'forms.virusScanRequired': {
+    defaultValue: false,
+    parse: parseBoolean,
+  },
+  'forms.maxSubmissionsPerIpPerDay': {
+    defaultValue: 50,
+    parse: parsePositiveInt('forms.maxSubmissionsPerIpPerDay', 100000),
+  },
+  // SSRF gate for definition webhooks: empty list = webhooks disabled until
+  // an admin explicitly allows destination hosts (changes are audited).
+  'forms.webhookAllowedHosts': {
+    defaultValue: [],
+    parse: parseStringArray('forms.webhookAllowedHosts', 50),
+  },
+  // Report builder (@ftisindia/report-builder) — runtime budgets and caps
+  // (report design §5.2/§8/§9). Typed, validated, audited like every setting.
+  'reports.statementTimeoutMs': {
+    defaultValue: 5000,
+    parse: parsePositiveInt('reports.statementTimeoutMs', 60000),
+  },
+  'reports.exportMaxSnapshotSeconds': {
+    defaultValue: 120,
+    parse: parsePositiveInt('reports.exportMaxSnapshotSeconds', 3600),
+  },
+  'reports.maxRowsSync': {
+    defaultValue: 10000,
+    parse: parsePositiveInt('reports.maxRowsSync', 100000),
+  },
+  'reports.countCap': {
+    defaultValue: 10000,
+    parse: parsePositiveInt('reports.countCap', 1000000),
+  },
+  'reports.liveTierMaxRows': {
+    defaultValue: 50000,
+    parse: parsePositiveInt('reports.liveTierMaxRows', 10000000),
+  },
+  // 0 disables the short-TTL result cache (report design §5.7).
+  'reports.resultCacheTtlMs': {
+    defaultValue: 0,
+    parse: parseNonNegativeInt('reports.resultCacheTtlMs', 300000),
+  },
+  // Curated tag vocabulary; empty = free-form tags (report design §7).
+  'reports.tagVocabulary': {
+    defaultValue: [],
+    parse: parseStringArray('reports.tagVocabulary', 200),
+  },
   timezone: {
     defaultValue: 'UTC',
     parse: parseTimezone,
@@ -101,6 +161,40 @@ function parseOptionalUrl(value: unknown) {
   }
 }
 
+function parseStringArray(key: string, maxItems: number) {
+  return (value: unknown) => {
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+      throw new BadRequestException(`${key} must be an array of strings.`);
+    }
+
+    if (value.length > maxItems) {
+      throw new BadRequestException(`${key} must not contain more than ${maxItems} items.`);
+    }
+
+    return value.map((item) => (item as string).trim()).filter((item) => item.length > 0);
+  };
+}
+
+function parsePositiveInt(key: string, max: number) {
+  return (value: unknown) => {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 1 || value > max) {
+      throw new BadRequestException(`${key} must be an integer between 1 and ${max}.`);
+    }
+
+    return value;
+  };
+}
+
+function parseNonNegativeInt(key: string, max: number) {
+  return (value: unknown) => {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0 || value > max) {
+      throw new BadRequestException(`${key} must be an integer between 0 and ${max}.`);
+    }
+
+    return value;
+  };
+}
+
 function parseTimezone(value: unknown) {
   if (typeof value !== 'string') {
     throw new BadRequestException('timezone must be a string.');