@ftisindia/create-app 0.1.5 → 0.2.0

package/template/prisma/migrations/20260613000000_add_report_builder/migration.sql

@@ -0,0 +1,129 @@
+-- CreateEnum
+CREATE TYPE "ReportDefinitionStatus" AS ENUM ('DRAFT', 'PUBLISHED', 'ARCHIVED');
+
+-- CreateEnum
+CREATE TYPE "ReportExportStatus" AS ENUM ('PENDING', 'RUNNING', 'DONE', 'FAILED');
+
+-- CreateEnum
+CREATE TYPE "ReportActionRunStatus" AS ENUM ('RUNNING', 'DONE', 'FAILED');
+
+-- CreateTable
+CREATE TABLE "ReportDefinition" (
+    "id" TEXT NOT NULL,
+    "orgId" TEXT NOT NULL,
+    "key" TEXT NOT NULL,
+    "version" INTEGER NOT NULL,
+    "status" "ReportDefinitionStatus" NOT NULL DEFAULT 'DRAFT',
+    "schema" JSONB NOT NULL,
+    "compiled" JSONB,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "ReportDefinition_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "ReportSavedView" (
+    "id" TEXT NOT NULL,
+    "orgId" TEXT NOT NULL,
+    "reportKey" TEXT NOT NULL,
+    "reportVersion" INTEGER NOT NULL,
+    "name" TEXT NOT NULL,
+    "spec" JSONB NOT NULL,
+    "ownerId" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "ReportSavedView_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "ReportExportJob" (
+    "id" TEXT NOT NULL,
+    "orgId" TEXT NOT NULL,
+    "reportKey" TEXT NOT NULL,
+    "reportVersion" INTEGER NOT NULL,
+    "spec" JSONB NOT NULL,
+    "asOf" TIMESTAMP(3),
+    "status" "ReportExportStatus" NOT NULL DEFAULT 'PENDING',
+    "fileId" TEXT,
+    "rowCount" INTEGER,
+    "error" TEXT,
+    "requestedBy" TEXT NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "ReportExportJob_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "ReportBulkActionRun" (
+    "id" TEXT NOT NULL,
+    "orgId" TEXT NOT NULL,
+    "reportKey" TEXT NOT NULL,
+    "reportVersion" INTEGER NOT NULL,
+    "action" TEXT NOT NULL,
+    "idempotencyKey" TEXT NOT NULL,
+    "status" "ReportActionRunStatus" NOT NULL DEFAULT 'RUNNING',
+    "result" JSONB,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "ReportBulkActionRun_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "ReportRowTag" (
+    "id" TEXT NOT NULL,
+    "orgId" TEXT NOT NULL,
+    "sourceKind" TEXT NOT NULL,
+    "sourceKey" TEXT NOT NULL,
+    "rowId" TEXT NOT NULL,
+    "tag" TEXT NOT NULL,
+    "createdBy" TEXT NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "ReportRowTag_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "ReportDefinition_orgId_key_version_key" ON "ReportDefinition"("orgId", "key", "version");
+
+-- CreateIndex
+CREATE INDEX "ReportDefinition_orgId_idx" ON "ReportDefinition"("orgId");
+
+-- CreateIndex
+CREATE INDEX "ReportDefinition_orgId_status_idx" ON "ReportDefinition"("orgId", "status");
+
+-- CreateIndex
+CREATE INDEX "ReportSavedView_orgId_reportKey_idx" ON "ReportSavedView"("orgId", "reportKey");
+
+-- CreateIndex
+CREATE INDEX "ReportExportJob_orgId_status_idx" ON "ReportExportJob"("orgId", "status");
+
+-- CreateIndex
+CREATE INDEX "ReportExportJob_orgId_createdAt_idx" ON "ReportExportJob"("orgId", "createdAt");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "ReportBulkActionRun_orgId_idempotencyKey_key" ON "ReportBulkActionRun"("orgId", "idempotencyKey");
+
+-- CreateIndex
+CREATE INDEX "ReportBulkActionRun_orgId_reportKey_action_idx" ON "ReportBulkActionRun"("orgId", "reportKey", "action");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "ReportRowTag_orgId_sourceKind_sourceKey_rowId_tag_key" ON "ReportRowTag"("orgId", "sourceKind", "sourceKey", "rowId", "tag");
+
+-- CreateIndex
+CREATE INDEX "ReportRowTag_orgId_sourceKind_sourceKey_tag_idx" ON "ReportRowTag"("orgId", "sourceKind", "sourceKey", "tag");
+
+-- CreateIndex
+CREATE INDEX "ReportRowTag_orgId_sourceKind_sourceKey_rowId_idx" ON "ReportRowTag"("orgId", "sourceKind", "sourceKey", "rowId");
+
+-- Partial unique indexes for saved-view names (report design §12, finding #5).
+-- Postgres treats NULLs as distinct, so a plain unique over nullable "ownerId"
+-- would not deduplicate SHARED views. Prisma cannot express partial indexes:
+-- if a later `prisma migrate dev` proposes dropping these, DELETE those DROP
+-- lines — the reports boot check fails fast when they are missing.
+CREATE UNIQUE INDEX "report_view_shared_uq"
+  ON "ReportSavedView" ("orgId", "reportKey", "name") WHERE "ownerId" IS NULL;
+CREATE UNIQUE INDEX "report_view_personal_uq"
+  ON "ReportSavedView" ("orgId", "reportKey", "ownerId", "name") WHERE "ownerId" IS NOT NULL;

package/template/prisma/migrations/20260616000000_add_form_outbox_claimed_by/migration.sql

@@ -0,0 +1,5 @@
+-- Add an opaque lease token for outbox claim ownership. Dispatchers must match
+-- this token when heartbeating or settling PROCESSING jobs.
+ALTER TABLE "FormOutboxJob" ADD COLUMN "claimedBy" TEXT;
+
+CREATE INDEX "FormOutboxJob_status_claimedBy_idx" ON "FormOutboxJob"("status", "claimedBy");

package/template/prisma/schema.prisma

@@ -297,3 +297,292 @@ model AuditLog {
   @@index([targetType, targetId])
   @@index([createdAt])
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// @ftisindia/form-builder — canonical Prisma model snippet (ENGINE_SCHEMA_VERSION 1)
+//
+// The APP owns schema.prisma and the migration history (ecosystem guide §10.1).
+// Copy these models into your app's prisma/schema.prisma verbatim and run
+// `prisma migrate dev`. The glue module's boot-time check verifies the live
+// database matches this snippet's tables/columns and fails fast otherwise.
+// Conventions follow the FTIS template: uuid() ids, UPPER_CASE enum values,
+// org-leading hot indexes, explicit orgId on every engine table.
+// ─────────────────────────────────────────────────────────────────────────────
+
+enum FormDefinitionStatus {
+  DRAFT
+  PUBLISHED
+  ARCHIVED
+}
+
+enum SubmissionStatus {
+  DRAFT
+  SUBMITTED
+}
+
+enum FormActionStatus {
+  OK
+  ERROR
+}
+
+enum OutboxStatus {
+  PENDING
+  PROCESSING
+  DONE
+  FAILED
+}
+
+enum FileStatus {
+  TEMPORARY
+  SCANNING
+  CLEAN
+  INFECTED
+  LINKED
+}
+
+model FormDefinition {
+  id     String               @id @default(uuid())
+  orgId  String
+  key    String
+  // Bumped on every published change; published rows are immutable.
+  version Int
+  status  FormDefinitionStatus @default(DRAFT)
+  // The full FormDefinition document (JSONB).
+  schema  Json
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([orgId, key, version])
+  @@index([orgId])
+  @@index([orgId, status])
+}
+
+model FormSubmission {
+  id      String @id @default(uuid())
+  orgId   String
+  formKey String
+  // The exact definition version the data was captured under. Non-negotiable.
+  formVersion Int
+  // Nested submission payload (JSONB) — submissions are documents, not rows.
+  data   Json
+  status SubmissionStatus @default(DRAFT)
+  // Set by the lockEditing action; locked submissions reject further edits.
+  locked Boolean @default(false)
+
+  createdBy String?
+  // Stamped only on anonymous/public submissions (abuse-control Tier 1).
+  ipAddress String?
+  userAgent String?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([orgId, formKey, status])
+  @@index([orgId, createdAt])
+  @@index([orgId, formKey, ipAddress, createdAt])
+}
+
+model FormActionLog {
+  id           String           @id @default(uuid())
+  orgId        String
+  submissionId String?
+  formKey      String
+  formVersion  Int?
+  action       String
+  status       FormActionStatus
+  // Redacted by the engine before write — sensitive fields never land here.
+  input        Json?
+  output       Json?
+  errorCode    String?
+  errorMessage String?
+  actorId      String?
+  requestId    String?
+  durationMs   Int?
+  createdAt    DateTime         @default(now())
+
+  @@index([orgId, createdAt])
+  @@index([orgId, formKey, action, status])
+}
+
+model FormOutboxJob {
+  id      String       @id @default(uuid())
+  type    String
+  payload Json
+  status  OutboxStatus @default(PENDING)
+
+  attempts    Int @default(0)
+  maxAttempts Int @default(8)
+  // Prevents double-send on retry (e.g. submissionId:type:action).
+  idempotencyKey String?   @unique
+  lastError      String?
+  runAfter       DateTime?
+  // Opaque worker lease token. Heartbeats and terminal transitions must match
+  // this value so a stale worker cannot finish another worker's reclaimed job.
+  claimedBy      String?
+
+  // Worker-context restoration + audit correlation (ecosystem guide §3).
+  orgId           String?
+  actorUserId     String?
+  originRequestId String?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([status, runAfter])
+  @@index([status, claimedBy])
+}
+
+model UploadedFile {
+  id           String @id @default(uuid())
+  storageKey   String @unique
+  originalName String
+  // SERVER-VERIFIED (sniffed) MIME type, never the client-sent Content-Type.
+  mimeType String
+  size     Int
+  // sha256 hex.
+  checksum String
+  // Two-factor ownership: uploader identity AND tenant scope (§10).
+  ownerId String
+  orgId   String
+
+  status       FileStatus @default(TEMPORARY)
+  submissionId String?
+
+  createdAt DateTime @default(now())
+
+  @@index([orgId, status])
+  @@index([ownerId, status])
+  @@index([status, createdAt])
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Report builder (@ftisindia/report-builder) — engine tables
+// (REPORTS_ENGINE_SCHEMA_VERSION 1). Copied from the engine's canonical
+// snippet (@ftisindia/report-builder/prisma/reports.prisma); the glue
+// module's boot check verifies the live database matches it. Sources stay
+// where they live — these are the engine's OWN tables only (report design §12).
+// ─────────────────────────────────────────────────────────────────────────────
+
+enum ReportDefinitionStatus {
+  DRAFT
+  PUBLISHED
+  ARCHIVED
+}
+
+enum ReportExportStatus {
+  PENDING
+  RUNNING
+  DONE
+  FAILED
+}
+
+enum ReportActionRunStatus {
+  RUNNING
+  DONE
+  FAILED
+}
+
+model ReportDefinition {
+  id      String                 @id @default(uuid())
+  orgId   String
+  key     String
+  // Bumped on every published change; published rows are immutable.
+  version Int
+  status  ReportDefinitionStatus @default(DRAFT)
+  // The full ReportDefinition document (JSONB).
+  schema  Json
+  // Set at publish: logical→physical column map + plan hashes (report design §5.2/§8.1).
+  compiled Json?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([orgId, key, version])
+  @@index([orgId])
+  @@index([orgId, status])
+}
+
+model ReportSavedView {
+  id            String   @id @default(uuid())
+  orgId         String
+  reportKey     String
+  // The definition version the view was authored against (report design §4).
+  reportVersion Int
+  name          String
+  // The saved QuerySpec (JSONB).
+  spec          Json
+  // null ⇒ shared with the whole org (creation gated by reports.update).
+  ownerId       String?
+  createdAt     DateTime @default(now())
+
+  @@index([orgId, reportKey])
+  // Uniqueness lives in PARTIAL UNIQUE INDEXES shipped as raw SQL inside the
+  // add_report_builder migration — Postgres treats NULLs as distinct, so a
+  // @@unique over nullable ownerId would NOT deduplicate shared views (report
+  // design §12, finding #5). If a later `prisma migrate dev` proposes
+  // DROP INDEX "report_view_shared_uq" / "report_view_personal_uq", DELETE
+  // those lines — the reports boot check fails fast if they go missing.
+}
+
+model ReportExportJob {
+  id            String             @id @default(uuid())
+  orgId         String
+  reportKey     String
+  // The version the export ran against (report design §9, finding #1).
+  reportVersion Int
+  // FULL export spec {spec, format, columns} — replayable, auditable (not a hash).
+  spec          Json
+  // REPEATABLE READ snapshot timestamp, set when the job runs (finding #8).
+  asOf          DateTime?
+  status        ReportExportStatus @default(PENDING)
+  // Reports-owned storage key once the async export lands in file storage.
+  fileId        String?
+  rowCount      Int?
+  error         String?
+  requestedBy   String
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([orgId, status])
+  @@index([orgId, createdAt])
+}
+
+model ReportBulkActionRun {
+  id             String                @id @default(uuid())
+  orgId          String
+  reportKey      String
+  reportVersion  Int
+  action         String
+  // Client-supplied; a retried execute with the same key returns the recorded
+  // outcome instead of re-running (report design §6.3, finding #7).
+  idempotencyKey String
+  status         ReportActionRunStatus @default(RUNNING)
+  result         Json?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([orgId, idempotencyKey])
+  @@index([orgId, reportKey, action])
+}
+
+model ReportRowTag {
+  id         String   @id @default(uuid())
+  orgId      String
+  // 'custom' | 'form' | any registered source-provider kind.
+  sourceKind String
+  // Custom source key or form key.
+  sourceKey  String
+  // The source's declared, STABLE row identity (report design §7).
+  rowId      String
+  // Normalized: lowercased, trimmed. Labels are single-valued by convention
+  // ("label:approved") — one table, one mechanism.
+  tag        String
+  createdBy  String
+  createdAt  DateTime @default(now())
+
+  @@unique([orgId, sourceKind, sourceKey, rowId, tag])
+  @@index([orgId, sourceKind, sourceKey, tag])
+  @@index([orgId, sourceKind, sourceKey, rowId])
+}

package/template/scripts/export-openapi.ts

@@ -0,0 +1,85 @@
+import { existsSync, readFileSync } from 'fs';
+import { writeFile } from 'fs/promises';
+import { resolve } from 'path';
+
+loadEnvFile();
+ensurePlaceholderEnv();
+
+main().catch((error: unknown) => {
+  console.error(error);
+  process.exit(1);
+});
+
+async function main() {
+  // Imported after env preparation so config validation sees the placeholders.
+  const { NestFactory } = await import('@nestjs/core');
+  const { SwaggerModule } = await import('@nestjs/swagger');
+  const { AppModule } = await import('../src/app.module');
+  const { buildOpenApiConfig } = await import('../src/config/openapi');
+
+  const app = await NestFactory.create(AppModule, {
+    logger: false,
+    abortOnError: false,
+  });
+
+  try {
+    const document = SwaggerModule.createDocument(app, buildOpenApiConfig());
+    const outputPath = resolve(process.cwd(), 'docs-json.json');
+    await writeFile(outputPath, `${JSON.stringify(document, null, 2)}\n`);
+    console.log(`OpenAPI document written to ${outputPath}`);
+  } finally {
+    await app.close().catch(() => undefined);
+  }
+}
+
+// The document is built from route metadata only; no server starts and no
+// database connection is made, so missing secrets get safe placeholders.
+function ensurePlaceholderEnv() {
+  if (!process.env.DATABASE_URL) {
+    process.env.DATABASE_URL =
+      'postgresql://placeholder:placeholder@localhost:5432/placeholder';
+  }
+
+  if (!process.env.JWT_SECRET) {
+    process.env.JWT_SECRET = 'openapi-export-placeholder-secret-0123456789';
+  }
+}
+
+function loadEnvFile() {
+  const envPath = resolve(process.cwd(), '.env');
+  if (!existsSync(envPath)) {
+    return;
+  }
+
+  const lines = readFileSync(envPath, 'utf8').split(/\r?\n/);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) {
+      continue;
+    }
+
+    const equalsIndex = trimmed.indexOf('=');
+    if (equalsIndex === -1) {
+      continue;
+    }
+
+    const key = trimmed.slice(0, equalsIndex).trim();
+    const rawValue = trimmed.slice(equalsIndex + 1).trim();
+    if (!key || process.env[key] !== undefined) {
+      continue;
+    }
+
+    process.env[key] = stripQuotes(rawValue);
+  }
+}
+
+function stripQuotes(value: string) {
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    return value.slice(1, -1);
+  }
+
+  return value;
+}

package/template/scripts/gen-form.mjs

@@ -0,0 +1,149 @@
+// Scaffold a form definition + a DB-free lint spec (definitions-as-code).
+//
+//   npm run gen:form -- customer-feedback
+//   npm run gen:form -- customer-feedback --title "Customer feedback"
+//
+// Generates:
+//   src/modules/forms/definitions/<key>.form.json   (starter definition)
+//   test/<key>.form.spec.ts                          (meta-schema + publish lint, runs in `npm test`)
+//
+// Load it into an organisation with:
+//   npm run forms:push -- --file src/modules/forms/definitions/<key>.form.json --org <org> --user <email> --publish
+
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+
+const args = process.argv.slice(2);
+const key = args[0];
+if (!key || key.startsWith('--')) {
+  throw new Error('Usage: npm run gen:form -- <form-key> [--title "Display title"]');
+}
+if (!/^[a-z0-9][a-z0-9-]*$/.test(key) || key.length > 100) {
+  throw new Error(
+    `Form key "${key}" is invalid. Use lowercase letters, digits, and hyphens (must start with a letter or digit).`,
+  );
+}
+
+const titleFlag = args.indexOf('--title');
+const title =
+  titleFlag !== -1 && args[titleFlag + 1]
+    ? args[titleFlag + 1]
+    : key
+        .split('-')
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(' ');
+
+const definitionPath = join('src', 'modules', 'forms', 'definitions', `${key}.form.json`);
+const specPath = join('test', `${key}.form.spec.ts`);
+
+for (const path of [definitionPath, specPath]) {
+  if (existsSync(path)) {
+    throw new Error(`Refusing to overwrite existing file: ${path}`);
+  }
+}
+
+const definition = {
+  key,
+  version: 1,
+  title,
+  fields: [
+    {
+      type: 'text',
+      name: 'title',
+      label: 'Title',
+      validators: { required: true, maxLength: 200 },
+      reportable: true,
+    },
+    {
+      type: 'text',
+      name: 'notes',
+      label: 'Notes',
+      validators: { maxLength: 2000 },
+    },
+  ],
+  actions: {
+    submit: ['validateAll', 'persist'],
+    saveDraft: ['persistDraft'],
+  },
+};
+
+const spec = `import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  ActionRegistry,
+  DEFAULT_ORG_FORMS_POLICY,
+  DEFAULT_RULE_LIMITS,
+  DataSourceRegistry,
+  FieldTypeRegistry,
+  lintDefinition,
+  lintRules,
+  registerBuiltinActions,
+  registerCoreFieldTypes,
+  validateDefinitionShape,
+} from '@ftisindia/form-builder';
+import type { FormDefinition, SubmissionStore } from '@ftisindia/form-builder';
+
+/**
+ * DB-free definition lint for ${key}.form.json — fails the unit-test run the
+ * moment the definition would be rejected at save/publish time. If your
+ * definition references custom actions or data sources, register matching
+ * stubs below (same names/kinds as the real providers).
+ */
+const definition = JSON.parse(
+  readFileSync(
+    join(__dirname, '..', 'src', 'modules', 'forms', 'definitions', '${key}.form.json'),
+    'utf8',
+  ),
+) as FormDefinition;
+
+describe('${key} form definition', () => {
+  const fieldTypes = new FieldTypeRegistry();
+  registerCoreFieldTypes(fieldTypes);
+
+  const actions = new ActionRegistry();
+  registerBuiltinActions(actions, {
+    validate: () => ({ valid: true, errors: [] }),
+    submissions: {} as SubmissionStore,
+  });
+  actions.register({ name: 'sendConfirmationEmail', kind: 'post-commit', execute: async () => ({}) });
+  actions.register({
+    name: 'authenticate',
+    kind: 'transactional',
+    dangerous: true,
+    execute: async () => ({}),
+  });
+
+  it('passes the engine meta-schema', () => {
+    expect(validateDefinitionShape(definition)).toEqual([]);
+  });
+
+  it('passes publish-stage linting', () => {
+    expect(
+      lintDefinition(definition, {
+        fieldTypes,
+        actions,
+        dataSources: new DataSourceRegistry(),
+        policy: { ...DEFAULT_ORG_FORMS_POLICY, allowedDangerousActions: ['authenticate'] },
+        ruleLimits: DEFAULT_RULE_LIMITS,
+        lintRules,
+        stage: 'publish',
+        canWireDangerous: true,
+      }),
+    ).toEqual([]);
+  });
+});
+`;
+
+mkdirSync(dirname(definitionPath), { recursive: true });
+writeFileSync(definitionPath, `${JSON.stringify(definition, null, 2)}\n`);
+writeFileSync(specPath, spec);
+
+console.log(`Created ${definitionPath}`);
+console.log(`Created ${specPath}`);
+console.log('');
+console.log('Next steps:');
+console.log('  1. Edit the definition (fields, rules, actions, settings).');
+console.log('  2. npm test                              # lint spec runs without a database');
+console.log(
+  `  3. npm run forms:push -- --file ${definitionPath.replaceAll('\\', '/')} --org <org-id-or-slug> --user <owner-email> --publish`,
+);