@ftisindia/create-app 0.1.4 → 0.1.6

package/template/src/modules/reports/infrastructure/schema-check/reports-schema-check.service.ts

@@ -0,0 +1,116 @@
+import { Injectable, Logger, OnApplicationBootstrap } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { Prisma } from '@prisma/client';
+import {
+  EXPECTED_REPORTS_SCHEMA,
+  REPORTS_ENGINE_SCHEMA_VERSION,
+  REPORTS_PARTIAL_UNIQUE_SQL,
+  REPORTS_PRISMA_SNIPPET_PATH,
+  REQUIRED_REPORTS_INDEXES,
+} from '@ftisindia/report-builder';
+import { PrismaService } from '../../../../database/prisma/prisma.service';
+
+/**
+ * Boot-time schema compatibility check (ecosystem guide §10.1): the app owns
+ * schema.prisma and migrations; the engine ships the canonical snippet and a
+ * tables/columns manifest. On mismatch the app fails fast at startup with an
+ * actionable message instead of crashing mid-request with a cryptic Prisma
+ * error. Beyond tables/columns, the saved-view name uniques are PARTIAL
+ * unique indexes Prisma cannot represent (report design §12, finding #5) —
+ * they are verified via pg_indexes so a `migrate dev` regression cannot ship
+ * silently. Escape hatch: REPORTS_SCHEMA_CHECK=off.
+ */
+@Injectable()
+export class ReportsSchemaCheckService implements OnApplicationBootstrap {
+  private readonly logger = new Logger('ReportsSchemaCheck');
+
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly config: ConfigService,
+  ) {}
+
+  async onApplicationBootstrap(): Promise<void> {
+    if (this.config.get<string>('reports.schemaCheck') === 'off') {
+      this.logger.warn('Reports schema check is disabled (REPORTS_SCHEMA_CHECK=off).');
+      return;
+    }
+    await this.check();
+    this.logger.log(
+      `Reports schema check passed (engine schema version ${REPORTS_ENGINE_SCHEMA_VERSION}).`,
+    );
+  }
+
+  async check(): Promise<void> {
+    const tableProblems = await this.missingTablesOrColumns();
+    const indexProblems = await this.missingPartialUniques();
+    const problems = [...tableProblems, ...indexProblems];
+
+    if (problems.length === 0) {
+      return;
+    }
+
+    const lines = [
+      `The database does not match @ftisindia/report-builder engine schema version ${REPORTS_ENGINE_SCHEMA_VERSION}:`,
+      ...problems.map((problem) => `  - ${problem}`),
+      `Fix: copy the canonical models from "${REPORTS_PRISMA_SNIPPET_PATH}" (in node_modules) into prisma/schema.prisma and run "npx prisma migrate dev".`,
+    ];
+    if (indexProblems.length > 0) {
+      lines.push(
+        'The saved-view name uniques are partial indexes Prisma cannot represent — re-apply them as raw SQL inside a migration:',
+        REPORTS_PARTIAL_UNIQUE_SQL,
+      );
+    }
+    lines.push('To bypass temporarily (NOT recommended), set REPORTS_SCHEMA_CHECK=off.');
+
+    throw new Error(lines.join('\n'));
+  }
+
+  private async missingTablesOrColumns(): Promise<string[]> {
+    const tables = EXPECTED_REPORTS_SCHEMA.map((expected) => expected.table);
+    const rows = await this.prisma.$queryRaw<Array<{ table_name: string; column_name: string }>>`
+      SELECT table_name, column_name
+      FROM information_schema.columns
+      WHERE table_schema = current_schema()
+        AND table_name IN (${Prisma.join(tables)})
+    `;
+
+    const present = new Map<string, Set<string>>();
+    for (const row of rows) {
+      const columns = present.get(row.table_name) ?? new Set<string>();
+      columns.add(row.column_name);
+      present.set(row.table_name, columns);
+    }
+
+    const problems: string[] = [];
+    for (const expected of EXPECTED_REPORTS_SCHEMA) {
+      const columns = present.get(expected.table);
+      if (!columns) {
+        problems.push(`missing table "${expected.table}"`);
+        continue;
+      }
+      const missingColumns = expected.columns.filter((column) => !columns.has(column));
+      if (missingColumns.length > 0) {
+        problems.push(
+          `table "${expected.table}" is missing column(s): ${missingColumns.join(', ')}`,
+        );
+      }
+    }
+
+    return problems;
+  }
+
+  private async missingPartialUniques(): Promise<string[]> {
+    const names = REQUIRED_REPORTS_INDEXES.map((index) => index.name);
+    const rows = await this.prisma.$queryRaw<Array<{ indexname: string }>>`
+      SELECT indexname
+      FROM pg_indexes
+      WHERE schemaname = current_schema()
+        AND indexname IN (${Prisma.join(names)})
+    `;
+
+    const present = new Set(rows.map((row) => row.indexname));
+    return REQUIRED_REPORTS_INDEXES.filter((index) => !present.has(index.name)).map(
+      (index) => `missing index "${index.name}" on "${index.table}" — ${index.description}`,
+    );
+  }
+}

package/template/src/modules/reports/infrastructure/storage/local-disk-export-storage.adapter.ts

@@ -0,0 +1,79 @@
+import { createReadStream } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve, sep } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import type { Readable } from 'node:stream';
+import { Injectable } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import type { ExportFileSink } from '@ftisindia/report-builder';
+
+/**
+ * Reports-OWNED export file storage (report design §9). The reports module
+ * keeps its own org-scoped export directory so it does not depend on the form
+ * builder's UploadedFile machinery — the engine core's standalone guarantee
+ * (§3.2) extends to the glue: ReportsModule needs no FormsModule.
+ *
+ * Files land under `<exportStorageDir>/<orgId>/<uuid>.<ext>`; the returned
+ * `fileId` is that storage key, stored on the ReportExportJob row and used by
+ * the download route. The key is server-generated (no user input), and reads
+ * are guarded against escaping the configured directory.
+ *
+ * Swap this for an S3/GCS-backed ExportFileSink without touching the engine or
+ * the rest of the glue.
+ */
+@Injectable()
+export class LocalDiskReportExportStorage implements ExportFileSink {
+  private readonly baseDir: string;
+
+  constructor(config: ConfigService) {
+    this.baseDir = resolve(config.get<string>('reports.exportStorageDir') ?? './var/report-exports');
+  }
+
+  async putStream(
+    opts: { orgId: string; ownerId: string; fileName: string; mimeType: string },
+    chunks: AsyncIterable<Uint8Array>,
+  ): Promise<{ fileId: string; size: number }> {
+    // Collected into one buffer before writing. Bounded by the engine's export
+    // caps (row limits + the snapshot duration bound, §9) long before memory
+    // becomes a concern.
+    const collected: Buffer[] = [];
+    for await (const chunk of chunks) {
+      collected.push(Buffer.from(chunk));
+    }
+    const bytes = Buffer.concat(collected);
+
+    const safeOrg = sanitizeSegment(opts.orgId);
+    const storageKey = `${safeOrg}/${randomUUID()}${extensionOf(opts.fileName)}`;
+    const absolute = this.resolveKey(storageKey);
+    await mkdir(dirname(absolute), { recursive: true });
+    await writeFile(absolute, bytes);
+
+    return { fileId: storageKey, size: bytes.byteLength };
+  }
+
+  /** A readable stream for the download route. Guarded against path traversal. */
+  read(storageKey: string): Readable {
+    return createReadStream(this.resolveKey(storageKey));
+  }
+
+  /** Resolve a storage key inside the base dir, rejecting any escape. */
+  private resolveKey(storageKey: string): string {
+    const absolute = resolve(join(this.baseDir, storageKey));
+    if (absolute !== this.baseDir && !absolute.startsWith(this.baseDir + sep)) {
+      throw new Error('Export storage key resolves outside the configured directory.');
+    }
+    return absolute;
+  }
+}
+
+/** Keep path segments to a safe alphabet (uuids / org ids are already safe). */
+function sanitizeSegment(segment: string): string {
+  return segment.replace(/[^A-Za-z0-9_-]/g, '_');
+}
+
+/** Server-controlled extension: a short alphanumeric suffix, or none. */
+function extensionOf(fileName: string): string {
+  const dot = fileName.lastIndexOf('.');
+  const extension = dot >= 0 ? fileName.slice(dot) : '';
+  return /^\.[A-Za-z0-9]+$/.test(extension) ? extension.toLowerCase() : '';
+}

package/template/src/modules/reports/infrastructure/stores/index.ts

@@ -0,0 +1,5 @@
+export * from './prisma-bulk-action-run.store';
+export * from './prisma-export-job.store';
+export * from './prisma-report-definition.store';
+export * from './prisma-row-tag.store';
+export * from './prisma-saved-view.store';

package/template/src/modules/reports/infrastructure/stores/prisma-bulk-action-run.store.ts

@@ -0,0 +1,89 @@
+import { Injectable } from '@nestjs/common';
+import { Prisma, ReportBulkActionRun as ReportBulkActionRunRow } from '@prisma/client';
+import type {
+  ActionRunStatus,
+  BulkActionRunRecord,
+  BulkActionRunStore,
+  NewBulkActionRunRecord,
+} from '@ftisindia/report-builder';
+import { PrismaService } from '../../../../database/prisma/prisma.service';
+
+/**
+ * The bulk-action idempotency ledger (report design §6.3, finding #7): the
+ * (orgId, idempotencyKey) unique makes `begin` an atomic claim — exactly one
+ * caller creates the RUNNING row; a retry gets the existing row back and
+ * returns the recorded outcome instead of re-running the verb.
+ */
+@Injectable()
+export class PrismaBulkActionRunStore implements BulkActionRunStore {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async begin(
+    record: NewBulkActionRunRecord,
+  ): Promise<{ created: boolean; run: BulkActionRunRecord }> {
+    try {
+      const row = await this.prisma.reportBulkActionRun.create({
+        data: {
+          orgId: record.orgId,
+          reportKey: record.reportKey,
+          reportVersion: record.reportVersion,
+          action: record.action,
+          idempotencyKey: record.idempotencyKey,
+          status: 'RUNNING',
+        },
+      });
+
+      return { created: true, run: this.toRecord(row) };
+    } catch (error) {
+      if (!(error instanceof Prisma.PrismaClientKnownRequestError) || error.code !== 'P2002') {
+        throw error;
+      }
+
+      const existing = await this.prisma.reportBulkActionRun.findUnique({
+        where: {
+          orgId_idempotencyKey: { orgId: record.orgId, idempotencyKey: record.idempotencyKey },
+        },
+      });
+
+      if (!existing) {
+        // The claiming row vanished between the conflict and the lookup —
+        // surface the original conflict rather than inventing state.
+        throw error;
+      }
+
+      return { created: false, run: this.toRecord(existing) };
+    }
+  }
+
+  async complete(
+    orgId: string,
+    id: string,
+    status: 'DONE' | 'FAILED',
+    result?: unknown,
+  ): Promise<void> {
+    await this.prisma.reportBulkActionRun.updateMany({
+      where: { id, orgId },
+      data: {
+        status,
+        ...(result !== undefined
+          ? { result: result === null ? Prisma.DbNull : (result as Prisma.InputJsonValue) }
+          : {}),
+      },
+    });
+  }
+
+  private toRecord(row: ReportBulkActionRunRow): BulkActionRunRecord {
+    return {
+      id: row.id,
+      orgId: row.orgId,
+      reportKey: row.reportKey,
+      reportVersion: row.reportVersion,
+      action: row.action,
+      idempotencyKey: row.idempotencyKey,
+      status: row.status as ActionRunStatus,
+      result: row.result,
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt,
+    };
+  }
+}

package/template/src/modules/reports/infrastructure/stores/prisma-export-job.store.ts

@@ -0,0 +1,93 @@
+import { Injectable } from '@nestjs/common';
+import { Prisma, ReportExportJob as ReportExportJobRow } from '@prisma/client';
+import type {
+  EngineTx,
+  ExportJobRecord,
+  ExportJobSpec,
+  ExportJobStatus,
+  ExportJobStore,
+  NewExportJobRecord,
+} from '@ftisindia/report-builder';
+import { PrismaService } from '../../../../database/prisma/prisma.service';
+
+@Injectable()
+export class PrismaExportJobStore implements ExportJobStore {
+  constructor(private readonly prisma: PrismaService) {}
+
+  private client(tx?: EngineTx) {
+    return tx ? (tx as unknown as Prisma.TransactionClient) : this.prisma;
+  }
+
+  async create(record: NewExportJobRecord, tx?: EngineTx): Promise<ExportJobRecord> {
+    const row = await this.client(tx).reportExportJob.create({
+      data: {
+        orgId: record.orgId,
+        reportKey: record.reportKey,
+        reportVersion: record.reportVersion,
+        // The FULL spec {spec, format, columns} — replayable and auditable,
+        // never a hash (report design §9, finding #1/#8).
+        spec: record.spec as unknown as Prisma.InputJsonValue,
+        status: 'PENDING',
+        requestedBy: record.requestedBy,
+      },
+    });
+
+    return this.toRecord(row);
+  }
+
+  async findById(orgId: string, id: string): Promise<ExportJobRecord | null> {
+    const row = await this.client().reportExportJob.findFirst({
+      where: { id, orgId },
+    });
+
+    return row ? this.toRecord(row) : null;
+  }
+
+  async markRunning(orgId: string, id: string): Promise<void> {
+    await this.client().reportExportJob.updateMany({
+      where: { id, orgId },
+      data: { status: 'RUNNING' },
+    });
+  }
+
+  async markDone(
+    orgId: string,
+    id: string,
+    outcome: { fileId: string; rowCount: number; asOf: Date },
+  ): Promise<void> {
+    await this.client().reportExportJob.updateMany({
+      where: { id, orgId },
+      data: {
+        status: 'DONE',
+        fileId: outcome.fileId,
+        rowCount: outcome.rowCount,
+        asOf: outcome.asOf,
+      },
+    });
+  }
+
+  async markFailed(orgId: string, id: string, error: string): Promise<void> {
+    await this.client().reportExportJob.updateMany({
+      where: { id, orgId },
+      data: { status: 'FAILED', error },
+    });
+  }
+
+  private toRecord(row: ReportExportJobRow): ExportJobRecord {
+    return {
+      id: row.id,
+      orgId: row.orgId,
+      reportKey: row.reportKey,
+      reportVersion: row.reportVersion,
+      spec: row.spec as unknown as ExportJobSpec,
+      asOf: row.asOf,
+      status: row.status as ExportJobStatus,
+      fileId: row.fileId,
+      rowCount: row.rowCount,
+      error: row.error,
+      requestedBy: row.requestedBy,
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt,
+    };
+  }
+}

package/template/src/modules/reports/infrastructure/stores/prisma-report-definition.store.ts

@@ -0,0 +1,171 @@
+import { Injectable } from '@nestjs/common';
+import { Prisma, ReportDefinition as ReportDefinitionRow } from '@prisma/client';
+import {
+  ReportConflictError,
+  ReportNotFoundError,
+  type CompiledDefinitionMeta,
+  type EngineTx,
+  type NewReportDefinitionRecord,
+  type ReportDefinition,
+  type ReportDefinitionPatch,
+  type ReportDefinitionRecord,
+  type ReportDefinitionStatus,
+  type ReportDefinitionStore,
+} from '@ftisindia/report-builder';
+import { PrismaService } from '../../../../database/prisma/prisma.service';
+
+@Injectable()
+export class PrismaReportDefinitionStore implements ReportDefinitionStore {
+  constructor(private readonly prisma: PrismaService) {}
+
+  private client(tx?: EngineTx) {
+    return tx ? (tx as unknown as Prisma.TransactionClient) : this.prisma;
+  }
+
+  async create(record: NewReportDefinitionRecord, tx?: EngineTx): Promise<ReportDefinitionRecord> {
+    try {
+      const row = await this.client(tx).reportDefinition.create({
+        data: {
+          orgId: record.orgId,
+          key: record.key,
+          version: record.version,
+          status: record.status,
+          schema: record.schema as unknown as Prisma.InputJsonValue,
+        },
+      });
+
+      return this.toRecord(row);
+    } catch (error) {
+      // The (orgId, key, version) unique — a concurrent draft/publish race.
+      if (error instanceof Prisma.PrismaClientKnownRequestError && error.code === 'P2002') {
+        throw new ReportConflictError(
+          `Report definition "${record.key}" v${record.version} already exists in this organisation.`,
+        );
+      }
+      throw error;
+    }
+  }
+
+  async update(
+    orgId: string,
+    key: string,
+    version: number,
+    patch: ReportDefinitionPatch,
+    tx?: EngineTx,
+  ): Promise<ReportDefinitionRecord> {
+    const client = this.client(tx);
+
+    const existing = await client.reportDefinition.findUnique({
+      where: { orgId_key_version: { orgId, key, version } },
+      select: { id: true },
+    });
+
+    if (!existing) {
+      throw new ReportNotFoundError(
+        `Report definition "${key}" v${version} was not found in this organisation.`,
+      );
+    }
+
+    const row = await client.reportDefinition.update({
+      where: { id: existing.id },
+      data: {
+        ...(patch.status !== undefined ? { status: patch.status } : {}),
+        ...(patch.schema !== undefined
+          ? { schema: patch.schema as unknown as Prisma.InputJsonValue }
+          : {}),
+        ...(patch.compiled !== undefined
+          ? {
+              compiled:
+                patch.compiled === null
+                  ? Prisma.DbNull
+                  : (patch.compiled as unknown as Prisma.InputJsonValue),
+            }
+          : {}),
+      },
+    });
+
+    return this.toRecord(row);
+  }
+
+  async findByKeyVersion(
+    orgId: string,
+    key: string,
+    version: number,
+    tx?: EngineTx,
+  ): Promise<ReportDefinitionRecord | null> {
+    const row = await this.client(tx).reportDefinition.findUnique({
+      where: { orgId_key_version: { orgId, key, version } },
+    });
+
+    return row ? this.toRecord(row) : null;
+  }
+
+  async findLatest(
+    orgId: string,
+    key: string,
+    status?: ReportDefinitionStatus,
+  ): Promise<ReportDefinitionRecord | null> {
+    const row = await this.client().reportDefinition.findFirst({
+      where: { orgId, key, ...(status ? { status } : {}) },
+      orderBy: { version: 'desc' },
+    });
+
+    return row ? this.toRecord(row) : null;
+  }
+
+  async findAllByKeyStatus(
+    orgId: string,
+    key: string,
+    status: ReportDefinitionStatus,
+    tx?: EngineTx,
+  ): Promise<ReportDefinitionRecord[]> {
+    const rows = await this.client(tx).reportDefinition.findMany({
+      where: { orgId, key, status },
+      orderBy: { version: 'desc' },
+    });
+
+    return rows.map((row) => this.toRecord(row));
+  }
+
+  async list(
+    orgId: string,
+    options: { status?: ReportDefinitionStatus; cursor?: string; limit: number },
+  ): Promise<ReportDefinitionRecord[]> {
+    const rows = await this.client().reportDefinition.findMany({
+      where: { orgId, ...(options.status ? { status: options.status } : {}) },
+      orderBy: [{ key: 'asc' }, { version: 'desc' }],
+      take: options.limit,
+      ...(options.cursor
+        ? {
+            cursor: { id: options.cursor },
+            skip: 1,
+          }
+        : {}),
+    });
+
+    return rows.map((row) => this.toRecord(row));
+  }
+
+  async maxVersion(orgId: string, key: string, tx?: EngineTx): Promise<number> {
+    const result = await this.client(tx).reportDefinition.aggregate({
+      _max: { version: true },
+      where: { orgId, key },
+    });
+
+    return result._max.version ?? 0;
+  }
+
+  private toRecord(row: ReportDefinitionRow): ReportDefinitionRecord {
+    return {
+      id: row.id,
+      orgId: row.orgId,
+      key: row.key,
+      version: row.version,
+      status: row.status as ReportDefinitionStatus,
+      schema: row.schema as unknown as ReportDefinition,
+      compiled: row.compiled === null ? null : (row.compiled as unknown as CompiledDefinitionMeta),
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt,
+    };
+  }
+}

package/template/src/modules/reports/infrastructure/stores/prisma-row-tag.store.ts

@@ -0,0 +1,110 @@
+import { Injectable } from '@nestjs/common';
+import { Prisma } from '@prisma/client';
+import type { EngineTx, RowTagStore } from '@ftisindia/report-builder';
+import { PrismaService } from '../../../../database/prisma/prisma.service';
+
+/**
+ * Org-scoped row tags & labels (report design §7): one table, one mechanism.
+ * The (orgId, sourceKind, sourceKey, rowId, tag) unique + createMany
+ * skipDuplicates make addTags idempotent per link; the engine normalizes tag
+ * text before it reaches this store.
+ */
+@Injectable()
+export class PrismaRowTagStore implements RowTagStore {
+  constructor(private readonly prisma: PrismaService) {}
+
+  private client(tx?: EngineTx) {
+    return tx ? (tx as unknown as Prisma.TransactionClient) : this.prisma;
+  }
+
+  async addTags(
+    orgId: string,
+    sourceKind: string,
+    sourceKey: string,
+    rowIds: readonly string[],
+    tags: readonly string[],
+    createdBy: string,
+    tx?: EngineTx,
+  ): Promise<number> {
+    if (rowIds.length === 0 || tags.length === 0) {
+      return 0;
+    }
+
+    const result = await this.client(tx).reportRowTag.createMany({
+      data: rowIds.flatMap((rowId) =>
+        tags.map((tag) => ({ orgId, sourceKind, sourceKey, rowId, tag, createdBy })),
+      ),
+      // Existing (org, source, row, tag) links are silently kept — the count
+      // returned is the number of NEW links, per the port contract.
+      skipDuplicates: true,
+    });
+
+    return result.count;
+  }
+
+  async removeTags(
+    orgId: string,
+    sourceKind: string,
+    sourceKey: string,
+    rowIds: readonly string[],
+    tags: readonly string[],
+    tx?: EngineTx,
+  ): Promise<number> {
+    if (rowIds.length === 0 || tags.length === 0) {
+      return 0;
+    }
+
+    const result = await this.client(tx).reportRowTag.deleteMany({
+      where: {
+        orgId,
+        sourceKind,
+        sourceKey,
+        rowId: { in: [...rowIds] },
+        tag: { in: [...tags] },
+      },
+    });
+
+    return result.count;
+  }
+
+  async tagsForRows(
+    orgId: string,
+    sourceKind: string,
+    sourceKey: string,
+    rowIds: readonly string[],
+  ): Promise<Map<string, string[]>> {
+    if (rowIds.length === 0) {
+      return new Map();
+    }
+
+    // One indexed lookup per page — (orgId, sourceKind, sourceKey, rowId).
+    const rows = await this.client().reportRowTag.findMany({
+      where: { orgId, sourceKind, sourceKey, rowId: { in: [...rowIds] } },
+      select: { rowId: true, tag: true },
+      orderBy: { tag: 'asc' },
+    });
+
+    const tagsByRow = new Map<string, string[]>();
+    for (const row of rows) {
+      const tags = tagsByRow.get(row.rowId);
+      if (tags) {
+        tags.push(row.tag);
+      } else {
+        tagsByRow.set(row.rowId, [row.tag]);
+      }
+    }
+
+    return tagsByRow;
+  }
+
+  async listTags(orgId: string, sourceKind: string, sourceKey: string): Promise<string[]> {
+    const rows = await this.client().reportRowTag.findMany({
+      where: { orgId, sourceKind, sourceKey },
+      select: { tag: true },
+      distinct: ['tag'],
+      orderBy: { tag: 'asc' },
+    });
+
+    return rows.map((row) => row.tag);
+  }
+}