@ftisindia/create-app 0.1.5 → 0.1.6

package/template/src/modules/reports/infrastructure/prisma-catalog.adapter.ts

@@ -0,0 +1,95 @@
+import { Injectable } from '@nestjs/common';
+import type { CatalogColumn, CatalogIndex, CatalogPort } from '@ftisindia/report-builder';
+import { PrismaService } from '../../../database/prisma/prisma.service';
+
+/**
+ * Catalog introspection for the publish-time lints (report design §5.2/§8):
+ * declared indexes are verified against pg_indexes, generated columns against
+ * information_schema, tier caps against the planner's pg_class estimates.
+ * Every lookup is scoped to current_schema() so other schemas (extensions,
+ * shadow databases) cannot shadow or leak into lint verdicts.
+ */
+@Injectable()
+export class PrismaReportsCatalog implements CatalogPort {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async indexesFor(table: string): Promise<CatalogIndex[]> {
+    const rows = await this.prisma.$queryRawUnsafe<
+      Array<{ indexname: string; tablename: string; indexdef: string }>
+    >(
+      `SELECT indexname, tablename, indexdef
+       FROM pg_indexes
+       WHERE schemaname = current_schema()
+         AND tablename = $1`,
+      table,
+    );
+
+    return rows.map((row) => ({
+      name: row.indexname,
+      table: row.tablename,
+      indexDef: row.indexdef,
+      isUnique: row.indexdef.includes('UNIQUE'),
+    }));
+  }
+
+  async columnsFor(table: string): Promise<CatalogColumn[]> {
+    const rows = await this.prisma.$queryRawUnsafe<
+      Array<{ column_name: string; data_type: string; is_generated: string }>
+    >(
+      `SELECT column_name, data_type, is_generated
+       FROM information_schema.columns
+       WHERE table_schema = current_schema()
+         AND table_name = $1`,
+      table,
+    );
+
+    return rows.map((row) => ({
+      name: row.column_name,
+      dataType: row.data_type,
+      isGenerated: row.is_generated === 'ALWAYS',
+    }));
+  }
+
+  async hasExtension(name: string): Promise<boolean> {
+    const rows = await this.prisma.$queryRawUnsafe<Array<{ found: number }>>(
+      `SELECT 1 AS found FROM pg_extension WHERE extname = $1`,
+      name,
+    );
+
+    return rows.length > 0;
+  }
+
+  async estimatedRowCount(table: string): Promise<number> {
+    const rows = await this.prisma.$queryRawUnsafe<Array<{ reltuples: unknown }>>(
+      `SELECT c.reltuples
+       FROM pg_class c
+       JOIN pg_namespace n ON n.oid = c.relnamespace
+       WHERE n.nspname = current_schema()
+         AND c.relname = $1
+         AND c.relkind IN ('r', 'p')`,
+      table,
+    );
+
+    if (rows.length === 0) {
+      return 0;
+    }
+    const estimate = Number(rows[0].reltuples);
+    return Number.isFinite(estimate) ? Math.max(0, estimate) : 0;
+  }
+
+  async relationExists(name: string): Promise<boolean> {
+    // Tables, views, materialized views, and partitioned tables all count —
+    // the materialized tier reads from any of them (report design §8).
+    const rows = await this.prisma.$queryRawUnsafe<Array<{ found: number }>>(
+      `SELECT 1 AS found
+       FROM pg_class c
+       JOIN pg_namespace n ON n.oid = c.relnamespace
+       WHERE n.nspname = current_schema()
+         AND c.relname = $1
+         AND c.relkind IN ('r', 'v', 'm', 'p')`,
+      name,
+    );
+
+    return rows.length > 0;
+  }
+}

package/template/src/modules/reports/infrastructure/prisma-query-executor.ts

@@ -0,0 +1,103 @@
+import { Injectable } from '@nestjs/common';
+import { Prisma } from '@prisma/client';
+import { ReportQueryBudgetError, type QueryExecutor, type SqlRow } from '@ftisindia/report-builder';
+import { PrismaService } from '../../../database/prisma/prisma.service';
+
+/** Hard ceiling on the per-statement budget — matches Prisma's own tx limits. */
+const MAX_STATEMENT_TIMEOUT_MS = 600_000;
+
+function assertValidStatementTimeout(ms: number): void {
+  if (!Number.isInteger(ms) || ms < 1 || ms > MAX_STATEMENT_TIMEOUT_MS) {
+    throw new Error(
+      `Invalid report statement timeout: ${ms} (expected an integer between 1 and ${MAX_STATEMENT_TIMEOUT_MS} ms).`,
+    );
+  }
+}
+
+/** Postgres 57014 — 'canceling statement due to statement timeout'. */
+function isStatementTimeout(error: unknown): boolean {
+  if (error instanceof Prisma.PrismaClientKnownRequestError) {
+    const meta = error.meta as { code?: unknown } | undefined;
+    if (meta?.code === '57014') {
+      return true;
+    }
+  }
+  const message = error instanceof Error ? error.message : '';
+  return message.includes('57014') || message.includes('canceling statement due to statement timeout');
+}
+
+/**
+ * Runs one compiler-built statement under a SET LOCAL statement_timeout on an
+ * open transaction client. SQL identifiers come only from code-owned manifests
+ * and every VALUE travels as a positional $1..$n bind; SET LOCAL cannot take
+ * binds, so the timeout — a VALIDATED INTEGER — is the one sanctioned
+ * interpolation exception (report design §2.1/§5.2).
+ *
+ * Shared between PrismaQueryExecutor (one-off transactions) and
+ * PrismaSnapshotRunner (the export's REPEATABLE READ transaction).
+ */
+export async function runBoundedQuery(
+  client: Prisma.TransactionClient,
+  sql: string,
+  params: readonly unknown[],
+  opts: { statementTimeoutMs: number },
+): Promise<SqlRow[]> {
+  assertValidStatementTimeout(opts.statementTimeoutMs);
+  try {
+    await client.$executeRawUnsafe(`SET LOCAL statement_timeout = ${opts.statementTimeoutMs}`);
+    return await client.$queryRawUnsafe<SqlRow[]>(sql, ...params);
+  } catch (error) {
+    if (isStatementTimeout(error)) {
+      // The runtime backstop (§5.2): a pathological plan fails fast, typed.
+      throw new ReportQueryBudgetError();
+    }
+    throw error;
+  }
+}
+
+/**
+ * EXPLAIN (FORMAT JSON) for the plan lint and estimated counts (§5.2/§5.4).
+ * Postgres returns one row shaped [{ "QUERY PLAN": <document> }]; drivers may
+ * surface the json column already parsed or as a string — the engine expects
+ * the parsed array-root document either way.
+ */
+export async function runExplain(
+  client: Prisma.TransactionClient,
+  sql: string,
+  params: readonly unknown[],
+): Promise<unknown> {
+  const rows = await client.$queryRawUnsafe<Array<Record<string, unknown>>>(
+    `EXPLAIN (FORMAT JSON) ${sql}`,
+    ...params,
+  );
+  const plan = rows[0]?.['QUERY PLAN'];
+  return typeof plan === 'string' ? (JSON.parse(plan) as unknown) : plan;
+}
+
+/**
+ * The engine's SQL seam (report design §5) over Prisma. Each call runs inside
+ * its own short transaction because SET LOCAL is transaction-scoped — outside
+ * one it would be a silent no-op and the statement budget would not exist.
+ */
+@Injectable()
+export class PrismaQueryExecutor implements QueryExecutor {
+  constructor(private readonly prisma: PrismaService) {}
+
+  query(
+    sql: string,
+    params: readonly unknown[],
+    opts: { statementTimeoutMs: number },
+  ): Promise<SqlRow[]> {
+    assertValidStatementTimeout(opts.statementTimeoutMs);
+    return this.prisma.$transaction((tx) => runBoundedQuery(tx, sql, params, opts), {
+      // Keep Prisma's transaction window above the statement budget so the
+      // budget — not Prisma's 5s interactive-tx default — is what fires.
+      timeout: opts.statementTimeoutMs + 1000,
+      maxWait: 5000,
+    });
+  }
+
+  explain(sql: string, params: readonly unknown[]): Promise<unknown> {
+    return this.prisma.$transaction((tx) => runExplain(tx, sql, params));
+  }
+}

package/template/src/modules/reports/infrastructure/prisma-snapshot-runner.ts

@@ -0,0 +1,47 @@
+import { Injectable } from '@nestjs/common';
+import { Prisma } from '@prisma/client';
+import type { QueryExecutor, SnapshotRunner } from '@ftisindia/report-builder';
+import { PrismaService } from '../../../database/prisma/prisma.service';
+import { runBoundedQuery, runExplain } from './prisma-query-executor';
+
+/**
+ * One REPEATABLE READ transaction per export (report design §9, finding #8):
+ * every keyset batch reads the same MVCC snapshot, so rows moving under the
+ * export can neither be skipped nor duplicated. The transaction is
+ * duration-bounded — an export that cannot finish inside the bound aborts
+ * (and the engine maps that to guidance: tighten filters or move the report
+ * to the materialized tier).
+ */
+@Injectable()
+export class PrismaSnapshotRunner implements SnapshotRunner {
+  constructor(private readonly prisma: PrismaService) {}
+
+  withSnapshot<T>(
+    opts: { maxDurationMs: number },
+    fn: (exec: QueryExecutor, asOf: Date) => Promise<T>,
+  ): Promise<T> {
+    return this.prisma.$transaction(
+      async (tx) => {
+        // Under REPEATABLE READ now() is the transaction (= snapshot) start
+        // time — the export's `asOf`, stamped into the job and file metadata.
+        const rows = await tx.$queryRawUnsafe<Array<{ now: unknown }>>('SELECT now() AS now');
+        const now = rows[0]?.now;
+        const asOf = now instanceof Date ? now : new Date();
+
+        // Executor bound to THIS transaction: same SET LOCAL budget + EXPLAIN
+        // logic as PrismaQueryExecutor, valid only while `fn` runs.
+        const exec: QueryExecutor = {
+          query: (sql, params, queryOpts) => runBoundedQuery(tx, sql, params, queryOpts),
+          explain: (sql, params) => runExplain(tx, sql, params),
+        };
+
+        return fn(exec, asOf);
+      },
+      {
+        isolationLevel: Prisma.TransactionIsolationLevel.RepeatableRead,
+        timeout: opts.maxDurationMs,
+        maxWait: 5000,
+      },
+    );
+  }
+}

package/template/src/modules/reports/infrastructure/prisma-tx-runner.ts

@@ -0,0 +1,18 @@
+import { Injectable } from '@nestjs/common';
+import type { EngineTx, TxRunner } from '@ftisindia/report-builder';
+import { PrismaService } from '../../../database/prisma/prisma.service';
+
+/**
+ * The engine's transaction seam over PrismaService.$transaction. The opaque
+ * EngineTx brand is a Prisma.TransactionClient underneath; the stores cast it
+ * back. One TxRunner.run call is the engine's atomicity boundary (export job
+ * row + outbox enqueue, bulk-action ledger + audit — report design §6.3/§9).
+ */
+@Injectable()
+export class ReportsPrismaTxRunner implements TxRunner {
+  constructor(private readonly prisma: PrismaService) {}
+
+  run<T>(fn: (tx: EngineTx) => Promise<T>): Promise<T> {
+    return this.prisma.$transaction((tx) => fn(tx as unknown as EngineTx));
+  }
+}

package/template/src/modules/reports/infrastructure/registry/registry-bootstrap.service.ts

@@ -0,0 +1,61 @@
+import { Injectable, OnModuleInit } from '@nestjs/common';
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import {
+  ReportRowActionRegistry,
+  ReportSourceRegistry,
+  ReportTagService,
+  SourceProviderRegistry,
+  createCustomSourceProvider,
+  createManageTagsAction,
+} from '@ftisindia/report-builder';
+import type { ReportRowActionDef, ReportSourceDef } from '@ftisindia/report-builder';
+import {
+  REPORT_ROW_ACTION_METADATA,
+  REPORT_SOURCE_METADATA,
+} from './report-extension.decorators';
+
+/**
+ * Populates the engine registries at startup — WITHOUT any form-builder
+ * dependency (the standalone guarantee extends to the glue, report design
+ * §3.2): the built-in manageTags action (§7), the 'custom' source provider
+ * over the code-owned source registry (the one provider the core ships), and
+ * a discovery scan for every app provider decorated with @ReportSource /
+ * @ReportRowAction (e.g. the org-members example source).
+ *
+ * Form-backed sources and the delegated editSubmission/updateStatus verbs are
+ * added by the OPTIONAL ReportsFormsModule, which registers the 'form'
+ * provider + actions into these same registries only when the app ships forms.
+ */
+@Injectable()
+export class ReportsRegistryBootstrapService implements OnModuleInit {
+  constructor(
+    private readonly discovery: DiscoveryService,
+    private readonly reflector: Reflector,
+    private readonly sourceRegistry: ReportSourceRegistry,
+    private readonly sourceProviders: SourceProviderRegistry,
+    private readonly actionRegistry: ReportRowActionRegistry,
+    private readonly tagService: ReportTagService,
+  ) {}
+
+  onModuleInit(): void {
+    this.actionRegistry.register(createManageTagsAction(this.tagService));
+    this.sourceProviders.register(createCustomSourceProvider(this.sourceRegistry));
+
+    for (const wrapper of this.discovery.getProviders()) {
+      const instance: unknown = wrapper.instance;
+      if (!instance || typeof instance !== 'object') {
+        continue;
+      }
+      const ctor = instance.constructor as object | undefined;
+      if (!ctor || ctor === Object) {
+        continue;
+      }
+      if (this.reflector.get<boolean>(REPORT_SOURCE_METADATA, ctor as never)) {
+        this.sourceRegistry.register(instance as ReportSourceDef);
+      }
+      if (this.reflector.get<boolean>(REPORT_ROW_ACTION_METADATA, ctor as never)) {
+        this.actionRegistry.register(instance as ReportRowActionDef);
+      }
+    }
+  }
+}

package/template/src/modules/reports/infrastructure/registry/report-extension.decorators.ts

@@ -0,0 +1,14 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const REPORT_SOURCE_METADATA = 'ftis:reports:source';
+export const REPORT_ROW_ACTION_METADATA = 'ftis:reports:row-action';
+
+/**
+ * The standardized extension story (report design §3.2/§6): implement the
+ * engine interface (ReportSourceDef / ReportRowActionDef), decorate the
+ * @Injectable class, list it as a provider — ReportsRegistryBootstrapService
+ * discovers and registers it at startup. Same three steps as the form
+ * registries.
+ */
+export const ReportSource = () => SetMetadata(REPORT_SOURCE_METADATA, true);
+export const ReportRowAction = () => SetMetadata(REPORT_ROW_ACTION_METADATA, true);

package/template/src/modules/reports/infrastructure/reports-job-queue.adapter.ts

@@ -0,0 +1,28 @@
+import { Injectable } from '@nestjs/common';
+import type { EngineTx, ReportsJobQueue } from '@ftisindia/report-builder';
+
+/**
+ * The async-export job queue (report design §9). The durable signal IS the
+ * `ReportExportJob` row the engine creates in the same transaction — the
+ * reports-owned ReportsExportDispatcherService polls that table for PENDING
+ * jobs. So `enqueue` is intentionally a no-op: there is no separate queue to
+ * write, and reports stays independent of the forms outbox.
+ *
+ * (An app that prefers an external queue can bind a different ReportsJobQueue
+ * — e.g. one that publishes to SQS — without changing the engine.)
+ */
+@Injectable()
+export class ReportsJobQueueNoop implements ReportsJobQueue {
+  async enqueue(
+    _job: {
+      type: string;
+      payload: Record<string, unknown>;
+      orgId: string;
+      actorUserId?: string | null;
+      idempotencyKey?: string;
+    },
+    _tx: EngineTx,
+  ): Promise<void> {
+    // The ReportExportJob row (committed with this tx) is the queue entry.
+  }
+}

package/template/src/modules/reports/infrastructure/request-reports-context.ts

@@ -0,0 +1,42 @@
+import { Injectable } from '@nestjs/common';
+import type { ReportsContext } from '@ftisindia/report-builder';
+import { RequestContextService } from '../../request-context/application/services/request-context.service';
+
+/**
+ * Binds the engine's ReportsContext seam to the app's AsyncLocalStorage
+ * request context (report design §13). Worker contexts (async export jobs)
+ * are restored by the forms outbox dispatcher before the engine runs, so the
+ * same adapter serves HTTP and worker callers (ecosystem guide §3).
+ */
+@Injectable()
+export class RequestReportsContext implements ReportsContext {
+  constructor(private readonly ctx: RequestContextService) {}
+
+  requestId() {
+    return this.ctx.getRequestId();
+  }
+
+  source(): 'http' | 'worker' {
+    return this.ctx.get()?.source ?? 'worker';
+  }
+
+  userId() {
+    return this.ctx.getUserId();
+  }
+
+  orgId() {
+    return this.ctx.getOrgId();
+  }
+
+  permissionKeys() {
+    return this.ctx.getPermissions();
+  }
+
+  isOwner() {
+    return this.ctx.getRbacContext()?.isOwner ?? false;
+  }
+
+  assertOrgScope(orgId: string) {
+    this.ctx.assertOrgScope(orgId);
+  }
+}

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';