create-forgeon 0.3.5 → 0.3.6

package/templates/module-fragments/files-access/10_overview.md

@@ -0,0 +1,9 @@
+## Overview
+
+`files-access` adds resource-level authorization checks on top of `files`.
+
+It provides:
+- `@forgeon/files-access` package
+- actor extraction helpers for request/user context
+- policy service with owner/public/permission checks
+- enforcement hooks in files controller routes

package/templates/module-fragments/files-access/20_scope.md

@@ -0,0 +1,20 @@
+## Scope
+
+Current stage:
+- requires `files-runtime` capability (`files` module)
+- protects:
+  - `GET /api/files/:publicId`
+  - `GET /api/files/:publicId/download`
+  - `DELETE /api/files/:publicId`
+- adds probe endpoint:
+  - `GET /api/health/files-access`
+
+Current policy:
+- allow when `files.manage` permission is present
+- allow owner (`ownerType=user` and `ownerId===actorId`)
+- allow read for `visibility=public`
+
+Future work:
+- integrate richer actor context from auth/rbac modules
+- extend policy for group/tenant membership
+- move toward dedicated `files-access` integration strategy for domain rules

package/templates/module-fragments/files-access/90_status_implemented.md

@@ -0,0 +1,3 @@
+## Status
+
+Implemented (runtime access-policy stage) and applied by `create-forgeon add files-access`.

package/templates/module-fragments/files-image/00_title.md

@@ -0,0 +1 @@
+# {{MODULE_LABEL}}

package/templates/module-fragments/files-image/10_overview.md

@@ -0,0 +1,10 @@
+## Overview
+
+`files-image` adds an image sanitation pipeline on top of `files`.
+
+It provides:
+- magic-bytes detection for actual file type
+- declared/detected MIME mismatch rejection
+- decode -> sanitize -> re-encode flow via `sharp`
+- default metadata stripping before storage
+- optional `preview` variant generation for files runtime

package/templates/module-fragments/files-image/20_scope.md

@@ -0,0 +1,20 @@
+## Scope
+
+Current stage:
+- requires `files-runtime` capability (`files` module)
+- supports image sanitization for:
+  - `image/jpeg`
+  - `image/png`
+  - `image/webp`
+- integrates into files upload flow before storage write
+- adds probe endpoint:
+  - `GET /api/health/files-image`
+
+Default policy:
+- `FILES_IMAGE_STRIP_METADATA=true`
+- metadata is removed unless explicitly disabled by config
+
+Future work:
+- richer resize/thumbnail presets
+- optional async processing mode
+- extended format support based on project needs

package/templates/module-fragments/files-image/90_status_implemented.md

@@ -0,0 +1,3 @@
+## Status
+
+Implemented (runtime image-sanitize stage) and applied by `create-forgeon add files-image`.

package/templates/module-fragments/files-local/00_title.md

@@ -0,0 +1 @@
+# {{MODULE_LABEL}}

package/templates/module-fragments/files-local/10_overview.md

@@ -0,0 +1,9 @@
+## Overview
+
+`files-local` is the local-disk provider for the `files-storage-adapter` capability.
+
+It provides:
+- `@forgeon/files-local` package
+- local storage config/env wiring in API runtime
+
+Use this provider as the default foundation for local development and simple deployments.

package/templates/module-fragments/files-local/20_scope.md

@@ -0,0 +1,10 @@
+## Scope
+
+Current stage:
+- used by `files` runtime when `FILES_STORAGE_DRIVER=local`
+- local root configuration via `FILES_LOCAL_ROOT`
+- Docker compose named volume `files_data` is mounted to `/app/storage`
+
+Future work:
+- local storage operational hardening
+- optional Docker volume presets via dedicated follow-up task/module

package/templates/module-fragments/files-local/90_status_implemented.md

@@ -0,0 +1,3 @@
+## Status
+
+Implemented (runtime local-provider stage) and applied by `create-forgeon add files-local`.

package/templates/module-fragments/files-quotas/00_title.md

@@ -0,0 +1 @@
+# {{MODULE_LABEL}}

package/templates/module-fragments/files-quotas/10_overview.md

@@ -0,0 +1,9 @@
+## Overview
+
+`files-quotas` adds owner-level upload limits on top of `files`.
+
+It provides:
+- `@forgeon/files-quotas` package
+- quota config/env module
+- quota evaluation service
+- upload pre-check hook in files controller

package/templates/module-fragments/files-quotas/20_scope.md

@@ -0,0 +1,20 @@
+## Scope
+
+Current stage:
+- requires `files-runtime` capability (`files` module)
+- owner-based limits:
+  - max files per owner
+  - max total bytes per owner
+- upload check runs before file write
+- probe endpoint:
+  - `GET /api/health/files-quotas`
+
+Current limitations:
+- per-owner only
+- no tenant-wide or group-wide aggregation yet
+- no async reconciliation job yet
+
+Future work:
+- richer quota subjects (`tenant`, `group`)
+- reconciliation support for drift correction
+- integration with future `files-quotas` accounting enhancements

package/templates/module-fragments/files-quotas/90_status_implemented.md

@@ -0,0 +1,3 @@
+## Status
+
+Implemented (runtime owner-quota stage) and applied by `create-forgeon add files-quotas`.

package/templates/module-fragments/files-s3/00_title.md

@@ -0,0 +1 @@
+# {{MODULE_LABEL}}

package/templates/module-fragments/files-s3/10_overview.md

@@ -0,0 +1,17 @@
+## Overview
+
+`files-s3` is the S3-compatible provider for the `files-storage-adapter` capability.
+
+It is intended for:
+- AWS S3
+- Cloudflare R2
+- MinIO
+- other S3-compatible endpoints
+
+This module provides runtime S3 storage integration used by `files` when `FILES_STORAGE_DRIVER=s3`.
+
+It includes provider tuning presets:
+- `minio` (default local/dev preset)
+- `aws`
+- `r2`
+- `custom`

package/templates/module-fragments/files-s3/20_scope.md

@@ -0,0 +1,11 @@
+## Scope
+
+Current stage:
+- provider config and env surface
+- runtime S3 storage is wired through the files service
+- provider presets (`minio | r2 | aws | custom`) with override-friendly env keys
+- retry tuning via `FILES_S3_MAX_ATTEMPTS`
+- empty `FILES_S3_REGION` / `FILES_S3_ENDPOINT` / `FILES_S3_FORCE_PATH_STYLE` use preset defaults
+
+Future work:
+- upload/download and signed URL strategy integration in `files`

package/templates/module-fragments/files-s3/90_status_implemented.md

@@ -0,0 +1,5 @@
+## Status
+
+Implemented and applied by `create-forgeon add files-s3`:
+- runtime baseline
+- provider presets (`minio | r2 | aws | custom`)

package/templates/module-fragments/queue/20_scope.md

@@ -1,7 +1,8 @@
-## Scope (Planned)
-
-Planned implementation target:
-
-1. Add queue package preset (worker + producer abstractions).
-2. Wire module imports and config in `apps/api`.
-3. Document runtime and deployment notes.
+## Scope
+
+Current implementation includes:
+
+1. Queue runtime package preset (`@forgeon/queue`) with Redis-backed BullMQ queue service.
+2. API wiring in `AppModule` (config loader + env schema + queue module import).
+3. Queue probe endpoint (`GET /api/health/queue`) and web probe button wiring.
+4. Docker Compose Redis service + API queue env wiring.

package/templates/module-fragments/queue/90_status_implemented.md

@@ -0,0 +1,3 @@
+## Status
+
+Implemented in the current scaffold.

package/templates/module-presets/files/apps/api/prisma/migrations/20260306_files_file_record/migration.sql

@@ -0,0 +1,30 @@
+-- CreateTable
+CREATE TABLE "FileRecord" (
+    "id" TEXT NOT NULL,
+    "publicId" TEXT NOT NULL,
+    "storageKey" TEXT NOT NULL,
+    "originalName" TEXT NOT NULL,
+    "mimeType" TEXT NOT NULL,
+    "size" INTEGER NOT NULL,
+    "storageDriver" TEXT NOT NULL,
+    "ownerType" TEXT NOT NULL DEFAULT 'system',
+    "ownerId" TEXT,
+    "visibility" TEXT NOT NULL DEFAULT 'private',
+    "createdById" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "FileRecord_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "FileRecord_publicId_key" ON "FileRecord"("publicId");
+
+-- CreateIndex
+CREATE INDEX "FileRecord_ownerType_ownerId_createdAt_idx" ON "FileRecord"("ownerType", "ownerId", "createdAt");
+
+-- CreateIndex
+CREATE INDEX "FileRecord_createdById_createdAt_idx" ON "FileRecord"("createdById", "createdAt");
+
+-- CreateIndex
+CREATE INDEX "FileRecord_visibility_createdAt_idx" ON "FileRecord"("visibility", "createdAt");

package/templates/module-presets/files/apps/api/prisma/migrations/20260306_files_file_variant/migration.sql

@@ -0,0 +1,55 @@
+-- CreateTable
+CREATE TABLE "FileBlob" (
+    "id" TEXT NOT NULL,
+    "hash" TEXT NOT NULL,
+    "size" INTEGER NOT NULL,
+    "mimeType" TEXT NOT NULL,
+    "storageDriver" TEXT NOT NULL,
+    "storageKey" TEXT NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "FileBlob_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "FileVariant" (
+    "id" TEXT NOT NULL,
+    "fileId" TEXT NOT NULL,
+    "variantKey" TEXT NOT NULL,
+    "blobId" TEXT NOT NULL,
+    "mimeType" TEXT NOT NULL,
+    "size" INTEGER NOT NULL,
+    "status" TEXT NOT NULL DEFAULT 'ready',
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "FileVariant_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "FileBlob_hash_size_mimeType_storageDriver_key" ON "FileBlob"("hash", "size", "mimeType", "storageDriver");
+
+-- CreateIndex
+CREATE INDEX "FileBlob_storageDriver_createdAt_idx" ON "FileBlob"("storageDriver", "createdAt");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "FileVariant_fileId_variantKey_key" ON "FileVariant"("fileId", "variantKey");
+
+-- CreateIndex
+CREATE INDEX "FileVariant_blobId_idx" ON "FileVariant"("blobId");
+
+-- CreateIndex
+CREATE INDEX "FileVariant_variantKey_status_idx" ON "FileVariant"("variantKey", "status");
+
+-- AddForeignKey
+ALTER TABLE "FileVariant"
+ADD CONSTRAINT "FileVariant_fileId_fkey"
+FOREIGN KEY ("fileId") REFERENCES "FileRecord"("id")
+ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "FileVariant"
+ADD CONSTRAINT "FileVariant_blobId_fkey"
+FOREIGN KEY ("blobId") REFERENCES "FileBlob"("id")
+ON DELETE RESTRICT ON UPDATE CASCADE;

package/templates/module-presets/files/packages/files/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@forgeon/files",
+  "version": "0.1.0",
+  "private": true,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@forgeon/db-prisma": "workspace:*",
+    "@nestjs/common": "^11.0.1",
+    "@nestjs/config": "^4.0.0",
+    "@nestjs/platform-express": "^11.0.1",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.14.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.10.7",
+    "typescript": "^5.7.3"
+  }
+}

package/templates/module-presets/files/packages/files/src/dto/create-file.dto.ts

@@ -0,0 +1,30 @@
+import { Transform } from 'class-transformer';
+import { IsIn, IsOptional, IsString, MaxLength } from 'class-validator';
+
+const visibilityValues = ['private', 'members', 'public'] as const;
+type FileVisibility = (typeof visibilityValues)[number];
+
+export class CreateFileDto {
+  @IsOptional()
+  @IsString()
+  @MaxLength(32)
+  @Transform(({ value }) => (typeof value === 'string' ? value.trim() : value))
+  ownerType?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(191)
+  @Transform(({ value }) => (typeof value === 'string' ? value.trim() : value))
+  ownerId?: string;
+
+  @IsOptional()
+  @IsString()
+  @IsIn(visibilityValues)
+  visibility?: FileVisibility;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(191)
+  @Transform(({ value }) => (typeof value === 'string' ? value.trim() : value))
+  createdById?: string;
+}

package/templates/module-presets/files/packages/files/src/files-config.loader.ts

@@ -0,0 +1,21 @@
+import { registerAs } from '@nestjs/config';
+import { parseFilesEnv } from './files-env.schema';
+
+export type FilesConfigValue = {
+  enabled: boolean;
+  storageDriver: 'local' | 's3';
+  publicBasePath: string;
+  maxFileSizeBytes: number;
+  allowedMimePrefixes: string[];
+};
+
+export const filesConfig = registerAs('files', (): FilesConfigValue => {
+  const env = parseFilesEnv(process.env);
+  return {
+    enabled: env.FILES_ENABLED,
+    storageDriver: env.FILES_STORAGE_DRIVER,
+    publicBasePath: env.FILES_PUBLIC_BASE_PATH,
+    maxFileSizeBytes: env.FILES_MAX_FILE_SIZE_BYTES,
+    allowedMimePrefixes: env.FILES_ALLOWED_MIME_PREFIXES,
+  };
+});

package/templates/module-presets/files/packages/files/src/files-config.module.ts

@@ -0,0 +1,12 @@
+import { Global, Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { filesConfig } from './files-config.loader';
+import { FilesConfigService } from './files-config.service';
+
+@Global()
+@Module({
+  imports: [ConfigModule.forFeature(filesConfig)],
+  providers: [FilesConfigService],
+  exports: [FilesConfigService],
+})
+export class FilesConfigModule {}

package/templates/module-presets/files/packages/files/src/files-config.service.ts

@@ -0,0 +1,32 @@
+import { Injectable } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import type { FilesConfigValue } from './files-config.loader';
+
+@Injectable()
+export class FilesConfigService {
+  constructor(private readonly configService: ConfigService) {}
+
+  get enabled(): boolean {
+    return this.configService.getOrThrow<FilesConfigValue['enabled']>('files.enabled');
+  }
+
+  get storageDriver(): FilesConfigValue['storageDriver'] {
+    return this.configService.getOrThrow<FilesConfigValue['storageDriver']>('files.storageDriver');
+  }
+
+  get publicBasePath(): string {
+    return this.configService.getOrThrow<FilesConfigValue['publicBasePath']>('files.publicBasePath');
+  }
+
+  get maxFileSizeBytes(): number {
+    return this.configService.getOrThrow<FilesConfigValue['maxFileSizeBytes']>(
+      'files.maxFileSizeBytes',
+    );
+  }
+
+  get allowedMimePrefixes(): string[] {
+    return this.configService.getOrThrow<FilesConfigValue['allowedMimePrefixes']>(
+      'files.allowedMimePrefixes',
+    );
+  }
+}

package/templates/module-presets/files/packages/files/src/files-env.schema.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+
+const filesEnvSchema = z.object({
+  FILES_ENABLED: z
+    .string()
+    .optional()
+    .default('true')
+    .transform((value) => value !== 'false'),
+  FILES_STORAGE_DRIVER: z.enum(['local', 's3']).optional().default('local'),
+  FILES_PUBLIC_BASE_PATH: z.string().optional().default('/files'),
+  FILES_MAX_FILE_SIZE_BYTES: z.coerce.number().int().positive().optional().default(10 * 1024 * 1024),
+  FILES_ALLOWED_MIME_PREFIXES: z
+    .string()
+    .optional()
+    .default('image/,application/pdf,text/')
+    .transform((value) =>
+      value
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean),
+    ),
+});
+
+export type FilesEnvSchema = z.infer<typeof filesEnvSchema>;
+
+export function parseFilesEnv(input: Record<string, string | undefined>): FilesEnvSchema {
+  return filesEnvSchema.parse(input);
+}
+
+export const filesEnvSchemaZod = filesEnvSchema;

package/templates/module-presets/files/packages/files/src/files.controller.ts

@@ -0,0 +1,89 @@
+import {
+  BadRequestException,
+  Body,
+  Controller,
+  Delete,
+  Get,
+  Param,
+  Post,
+  Query,
+  StreamableFile,
+  UploadedFile,
+  UseInterceptors,
+} from '@nestjs/common';
+import { FileInterceptor } from '@nestjs/platform-express';
+import { CreateFileDto } from './dto/create-file.dto';
+import { FilesService } from './files.service';
+import type { FileVariantKey } from './files.types';
+
+type UploadedFileShape = {
+  originalname: string;
+  mimetype: string;
+  size: number;
+  buffer: Buffer;
+};
+
+@Controller('files')
+export class FilesController {
+  constructor(private readonly filesService: FilesService) {}
+
+  @Post('upload')
+  @UseInterceptors(FileInterceptor('file'))
+  async uploadFile(
+    @UploadedFile() file: UploadedFileShape | undefined,
+    @Body() body: CreateFileDto,
+  ) {
+    if (!file || !file.buffer) {
+      throw new BadRequestException('File is required. Use multipart/form-data with field "file".');
+    }
+
+    return this.filesService.create({
+      originalName: file.originalname,
+      mimeType: file.mimetype,
+      size: file.size,
+      buffer: file.buffer,
+      ownerType: body.ownerType,
+      ownerId: body.ownerId,
+      visibility: body.visibility,
+      createdById: body.createdById,
+    });
+  }
+
+  @Get(':publicId')
+  async getMetadata(@Param('publicId') publicId: string) {
+    return this.filesService.getByPublicId(publicId);
+  }
+
+  @Get(':publicId/download')
+  async download(@Param('publicId') publicId: string, @Query('variant') variantQuery?: string) {
+    const variant = this.parseVariant(variantQuery);
+    const payload = await this.filesService.openDownload(publicId, variant);
+    return new StreamableFile(payload.stream, {
+      disposition: `inline; filename="${payload.fileName}"`,
+      type: payload.mimeType,
+    });
+  }
+
+  @Delete(':publicId')
+  async remove(@Param('publicId') publicId: string) {
+    return this.filesService.deleteByPublicId(publicId);
+  }
+
+  private parseVariant(variantQuery?: string): FileVariantKey {
+    if (!variantQuery || variantQuery.length === 0) {
+      return 'original';
+    }
+
+    if (variantQuery === 'original' || variantQuery === 'preview') {
+      return variantQuery;
+    }
+
+    throw new BadRequestException({
+      message: 'Unsupported file variant',
+      details: {
+        variant: variantQuery,
+        allowedVariants: ['original', 'preview'],
+      },
+    });
+  }
+}