create-easy-stack 1.0.3

package/infra/storage-cloudinary/files/src/core/infrastructure/storage/cloudinary-image-storage.ts

@@ -0,0 +1,158 @@
+import { Logger } from '@nestjs/common';
+import { v2 as cloudinary } from 'cloudinary';
+import { DomainException } from '../../domain/exceptions/domain.exception.js';
+import { StorageErrorCodes } from '../../domain/exceptions/error-codes.js';
+import type {
+  IImageStorage,
+  ImageFit,
+  ImageType,
+  ImageUpload,
+} from './image-storage.port.js';
+
+export interface CloudinarySettings {
+  cloudName: string;
+  apiKey: string;
+  apiSecret: string;
+  /** Everything of this app lives under this folder of the Cloudinary account. */
+  folder: string;
+}
+
+/** The two calls to Cloudinary that are needed; a stand-in replaces them in tests. */
+export interface CloudinaryClient {
+  upload(
+    image: Buffer,
+    options: Record<string, unknown>,
+  ): Promise<{ secure_url?: string }>;
+  destroy(publicId: string, options: Record<string, unknown>): Promise<unknown>;
+}
+
+const UPLOAD_TIMEOUT_MS = 15_000;
+// Cloudinary answers 400 for a file it cannot read as an image
+const CLOUDINARY_BAD_IMAGE = 400;
+// Names separated by single slashes; keeps a caller from reaching outside its folder
+const PATH_PATTERN = /^[A-Za-z0-9_-]+(\/[A-Za-z0-9_-]+)*$/;
+
+export const DEFAULT_IMAGE_FOLDER = '{{PROJECT_NAME}}';
+
+/** The real Cloudinary, using the official SDK; nothing is written to disk. */
+export function createCloudinaryClient(
+  settings: CloudinarySettings,
+): CloudinaryClient {
+  cloudinary.config({
+    cloud_name: settings.cloudName,
+    api_key: settings.apiKey,
+    api_secret: settings.apiSecret,
+    secure: true,
+  });
+  return {
+    upload: (image, options) =>
+      new Promise((resolve, reject) => {
+        cloudinary.uploader
+          .upload_stream(options, (error, result) =>
+            error || !result
+              ? reject(error ?? new Error('Cloudinary gave no result'))
+              : resolve(result),
+          )
+          .end(image);
+      }),
+    destroy: (publicId, options) =>
+      cloudinary.uploader.destroy(publicId, options),
+  };
+}
+
+export class CloudinaryImageStorage implements IImageStorage {
+  private readonly logger = new Logger(CloudinaryImageStorage.name);
+  private readonly addressStart: string;
+
+  constructor(
+    private readonly settings: CloudinarySettings,
+    private readonly client: CloudinaryClient = createCloudinaryClient(
+      settings,
+    ),
+  ) {
+    this.addressStart = `https://res.cloudinary.com/${settings.cloudName}/`;
+  }
+
+  async upload(request: ImageUpload): Promise<string> {
+    const publicId = this.publicId(request.path);
+    let result: { secure_url?: string };
+    try {
+      result = await this.client.upload(request.image, {
+        public_id: publicId,
+        resource_type: 'image',
+        // Uploading to the same path again replaces the picture instead of piling up files
+        overwrite: true,
+        invalidate: true,
+        unique_filename: false,
+        use_filename: false,
+        // Cloudinary checks the file again on its side
+        allowed_formats: [formatName(request.type)],
+        transformation: [transformationFor(request.fit)],
+        timeout: UPLOAD_TIMEOUT_MS,
+      });
+    } catch (error) {
+      if (
+        (error as { http_code?: number })?.http_code === CLOUDINARY_BAD_IMAGE
+      ) {
+        // Usually the file, but a bad option on our side looks the same: leave a trace
+        this.logger.warn(
+          `Cloudinary refused an image as unreadable: ${reasonOf(error)}`,
+        );
+        throw new DomainException(StorageErrorCodes.UNREADABLE_IMAGE);
+      }
+      // Only what went wrong, never the file or the keys
+      this.logger.error(`Uploading an image failed: ${reasonOf(error)}`);
+      throw new DomainException(StorageErrorCodes.UNAVAILABLE);
+    }
+
+    const address = result.secure_url;
+    if (typeof address !== 'string' || !address.startsWith(this.addressStart)) {
+      this.logger.error(
+        'Cloudinary answered with an address outside the configured cloud',
+      );
+      throw new DomainException(StorageErrorCodes.UNAVAILABLE);
+    }
+    return address;
+  }
+
+  async delete(path: string): Promise<void> {
+    const publicId = this.publicId(path);
+    try {
+      await this.client.destroy(publicId, {
+        invalidate: true,
+        timeout: UPLOAD_TIMEOUT_MS,
+      });
+    } catch (error) {
+      this.logger.error(`Removing an image failed: ${reasonOf(error)}`);
+      throw new DomainException(StorageErrorCodes.UNAVAILABLE);
+    }
+  }
+
+  private publicId(path: string): string {
+    if (!PATH_PATTERN.test(path)) {
+      // A bug in the calling code, not something a user can cause
+      throw new Error(`Invalid image path "${path}"`);
+    }
+    return `${this.settings.folder}/${path}`;
+  }
+}
+
+function formatName(type: ImageType): string {
+  return type === 'jpeg' ? 'jpg' : type;
+}
+
+function transformationFor(fit: ImageFit): Record<string, unknown> {
+  return {
+    width: fit.width,
+    height: fit.height,
+    crop: fit.crop,
+    ...(fit.crop === 'fill' && fit.focus === 'face' && { gravity: 'face' }),
+    quality: 'auto',
+  };
+}
+
+function reasonOf(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  const message = (error as { message?: unknown } | null)?.message;
+  return typeof message === 'string' ? message : 'unknown error';
+}

package/infra/storage-cloudinary/files/src/core/infrastructure/storage/image-storage.factory.ts

@@ -0,0 +1,30 @@
+import type { IImageStorage } from './image-storage.port.js';
+import {
+  CloudinaryImageStorage,
+  DEFAULT_IMAGE_FOLDER,
+  type CloudinarySettings,
+} from './cloudinary-image-storage.js';
+import { UnconfiguredImageStorage } from './unconfigured-image-storage.js';
+
+/** The Cloudinary settings, or null when none are given (`validateEnv` makes sure it is all or none). */
+export function cloudinarySettingsFromEnv(
+  env: NodeJS.ProcessEnv,
+): CloudinarySettings | null {
+  const cloudName = env.CLOUDINARY_CLOUD_NAME?.trim();
+  const apiKey = env.CLOUDINARY_API_KEY?.trim();
+  const apiSecret = env.CLOUDINARY_API_SECRET?.trim();
+  if (!cloudName || !apiKey || !apiSecret) return null;
+  return {
+    cloudName,
+    apiKey,
+    apiSecret,
+    folder: env.CLOUDINARY_FOLDER?.trim() || DEFAULT_IMAGE_FOLDER,
+  };
+}
+
+export function createImageStorage(env: NodeJS.ProcessEnv): IImageStorage {
+  const settings = cloudinarySettingsFromEnv(env);
+  return settings
+    ? new CloudinaryImageStorage(settings)
+    : new UnconfiguredImageStorage();
+}

package/infra/storage-cloudinary/files/src/core/infrastructure/storage/image-storage.module.ts

@@ -0,0 +1,17 @@
+import { Global, Module } from '@nestjs/common';
+import { IMAGE_STORAGE } from './image-storage.port.js';
+import { createImageStorage } from './image-storage.factory.js';
+
+// Global: any feature (avatars now, product photos later) injects IMAGE_STORAGE without
+// importing a feature module. Cloudinary when its settings are present, otherwise uploads answer 503.
+@Global()
+@Module({
+  providers: [
+    {
+      provide: IMAGE_STORAGE,
+      useFactory: () => createImageStorage(process.env),
+    },
+  ],
+  exports: [IMAGE_STORAGE],
+})
+export class ImageStorageModule {}

package/infra/storage-cloudinary/files/src/core/infrastructure/storage/image-storage.port.ts

@@ -0,0 +1,38 @@
+/** The kinds of image that are accepted, decided from the first bytes of the file. */
+export type ImageType = 'jpeg' | 'png' | 'webp';
+
+/** How a picture is cut to size when it is stored. */
+export interface ImageFit {
+  width: number;
+  height: number;
+  /** `fill`: exactly this size, cutting the edges. `limit`: shrink to fit inside, never enlarge. */
+  crop: 'fill' | 'limit';
+  /** With `fill`, what to keep in the middle: a detected face (else the centre), or the centre. */
+  focus?: 'face' | 'center';
+}
+
+export interface ImageUpload {
+  /**
+   * Where the picture lives, as names separated by "/" (letters, digits, "_" and "-"), e.g.
+   * `avatars/123`. Uploading to a path that has a picture replaces it, so the caller decides
+   * whether a thing has one picture (a fixed path) or many (a path per picture).
+   */
+  path: string;
+  image: Buffer;
+  type: ImageType;
+  fit: ImageFit;
+}
+
+export const IMAGE_STORAGE = 'IImageStorage';
+
+/**
+ * Where pictures are kept (avatars now; product photos and the like later). The features know
+ * what to store and where, never which service does it.
+ */
+export interface IImageStorage {
+  /** Stores the picture and returns the https address it can be shown from. */
+  upload(request: ImageUpload): Promise<string>;
+
+  /** Removes the picture at this path. Succeeds when there is none. */
+  delete(path: string): Promise<void>;
+}

package/infra/storage-cloudinary/files/src/core/infrastructure/storage/image-type.spec.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest';
+import { detectImageType } from './image-type.js';
+
+const bytes = (...values: number[]) => Buffer.from(values);
+const ascii = (text: string) => Buffer.from(text, 'latin1');
+
+describe('detectImageType', () => {
+  it('recognises JPEG, PNG and WebP by their first bytes', () => {
+    expect(detectImageType(bytes(0xff, 0xd8, 0xff, 0xe0, 0, 0x10))).toBe(
+      'jpeg',
+    );
+    expect(
+      detectImageType(
+        bytes(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0),
+      ),
+    ).toBe('png');
+    expect(
+      detectImageType(
+        Buffer.concat([ascii('RIFF'), bytes(10, 0, 0, 0), ascii('WEBPVP8 ')]),
+      ),
+    ).toBe('webp');
+  });
+
+  it.each([
+    ['text renamed to .png', ascii('hello, I am not a picture')],
+    [
+      'SVG (it can carry scripts)',
+      ascii('<svg xmlns="http://www.w3.org/2000/svg"></svg>'),
+    ],
+    ['GIF', ascii('GIF89a......')],
+    ['PDF', ascii('%PDF-1.7 ...')],
+    ['a Windows program', ascii('MZ......')],
+    ['an HTML page', ascii('<html><script>alert(1)</script>')],
+    [
+      'RIFF that is not WebP (a WAV sound)',
+      Buffer.concat([ascii('RIFF'), bytes(10, 0, 0, 0), ascii('WAVEfmt ')]),
+    ],
+    ['a PNG cut inside its signature', bytes(0x89, 0x50, 0x4e, 0x47)],
+    ['two bytes of a JPEG', bytes(0xff, 0xd8)],
+    ['nothing', Buffer.alloc(0)],
+  ])('refuses %s', (_name, content) => {
+    expect(detectImageType(content)).toBeNull();
+  });
+
+  it('does not read past the end of a short RIFF header', () => {
+    expect(detectImageType(ascii('RIFF1234WEB'))).toBeNull();
+  });
+});

package/infra/storage-cloudinary/files/src/core/infrastructure/storage/image-type.ts

@@ -0,0 +1,25 @@
+import type { ImageType } from './image-storage.port.js';
+
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+const JPEG_SIGNATURE = [0xff, 0xd8, 0xff];
+
+const startsWith = (bytes: Buffer, signature: number[], offset = 0) =>
+  bytes.length >= offset + signature.length &&
+  signature.every((value, index) => bytes[offset + index] === value);
+
+const asciiAt = (bytes: Buffer, offset: number, text: string) =>
+  bytes.length >= offset + text.length &&
+  bytes.toString('latin1', offset, offset + text.length) === text;
+
+/**
+ * What kind of image these bytes are, from the first bytes of the file, or null when it is none
+ * of the accepted kinds. The file name and the Content-Type are written by whoever sends the
+ * file, so they prove nothing. SVG is left out on purpose: it can carry scripts.
+ */
+export function detectImageType(bytes: Buffer): ImageType | null {
+  if (startsWith(bytes, JPEG_SIGNATURE)) return 'jpeg';
+  if (startsWith(bytes, PNG_SIGNATURE)) return 'png';
+  // WebP is "RIFF", four bytes of size, then "WEBP"
+  if (asciiAt(bytes, 0, 'RIFF') && asciiAt(bytes, 8, 'WEBP')) return 'webp';
+  return null;
+}

package/infra/storage-cloudinary/files/src/core/infrastructure/storage/unconfigured-image-storage.ts

@@ -0,0 +1,19 @@
+import { DomainException } from '../../domain/exceptions/domain.exception.js';
+import { StorageErrorCodes } from '../../domain/exceptions/error-codes.js';
+import type { IImageStorage, ImageUpload } from './image-storage.port.js';
+
+/**
+ * Used when no image service is configured: uploading answers 503 and says why; everything else
+ * keeps working, and removing a picture has nothing to remove from.
+ */
+export class UnconfiguredImageStorage implements IImageStorage {
+  upload(_request: ImageUpload): Promise<string> {
+    return Promise.reject(
+      new DomainException(StorageErrorCodes.NOT_CONFIGURED),
+    );
+  }
+
+  delete(_path: string): Promise<void> {
+    return Promise.resolve();
+  }
+}

package/infra/storage-cloudinary/infra.json

@@ -0,0 +1,73 @@
+{
+  "id": "storage-cloudinary",
+  "label": "Image storage (Cloudinary, optional at runtime)",
+  "templates": ["nest-ddd"],
+  "dependencies": {
+    "cloudinary": "^2.11.0"
+  },
+  "env": [
+    "# Cloudinary — optional: leave all empty to disable uploads (all three or none)",
+    "CLOUDINARY_CLOUD_NAME=",
+    "CLOUDINARY_API_KEY=",
+    "CLOUDINARY_API_SECRET=",
+    "CLOUDINARY_FOLDER={{PROJECT_NAME}}/images"
+  ],
+  "inject": [
+    {
+      "file": "src/core/domain/exceptions/error-codes.ts",
+      "marker": "// @infra:error-codes",
+      "lines": [
+        "export const StorageErrorCodes = {",
+        "  NOT_CONFIGURED: {",
+        "    code: 'STO-001',",
+        "    message: 'Image upload is not available right now',",
+        "    status: HttpStatus.SERVICE_UNAVAILABLE,",
+        "  },",
+        "  UNAVAILABLE: {",
+        "    code: 'STO-002',",
+        "    message: 'The image could not be saved, please try again later',",
+        "    status: HttpStatus.SERVICE_UNAVAILABLE,",
+        "  },",
+        "  UNREADABLE_IMAGE: {",
+        "    code: 'STO-003',",
+        "    message: 'The file could not be read as an image',",
+        "    status: HttpStatus.BAD_REQUEST,",
+        "  },",
+        "};",
+        ""
+      ]
+    },
+    {
+      "file": "src/app.module.ts",
+      "marker": "// @infra:imports",
+      "lines": ["import { ImageStorageModule } from './core/infrastructure/storage/image-storage.module.js';"]
+    },
+    {
+      "file": "src/app.module.ts",
+      "marker": "// @infra:modules",
+      "lines": ["ImageStorageModule,"]
+    },
+    {
+      "file": "src/core/index.ts",
+      "marker": "// @infra:barrel",
+      "lines": [
+        "export * from './infrastructure/storage/image-storage.port.js';",
+        "export * from './infrastructure/storage/image-type.js';",
+        "export * from './infrastructure/storage/cloudinary-image-storage.js';",
+        "export * from './infrastructure/storage/unconfigured-image-storage.js';",
+        "export * from './infrastructure/storage/image-storage.factory.js';",
+        "export * from './infrastructure/storage/image-storage.module.js';"
+      ]
+    },
+    {
+      "file": "src/core/config/env.validation.ts",
+      "marker": "// @infra:env-imports",
+      "lines": ["import { validateStorageEnv } from './storage.env.js';"]
+    },
+    {
+      "file": "src/core/config/env.validation.ts",
+      "marker": "// @infra:env-checks",
+      "lines": ["validateStorageEnv(config, errors);"]
+    }
+  ]
+}

package/lib/fs-utils.mjs

@@ -0,0 +1,115 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Files that cannot live under their real name inside a template
+ * (git/npm would treat them as config of the *template repo* itself).
+ */
+const RENAMES = {
+  _gitignore: '.gitignore',
+  _npmrc: '.npmrc',
+};
+
+const SKIP_DIRS = new Set(['node_modules', 'dist', '.git']);
+
+function isBinary(buffer) {
+  return buffer.subarray(0, 8000).includes(0);
+}
+
+/** Replaces every `{{TOKEN}}` that exists in `vars`. Unknown tokens (e.g. Handlebars) are left alone. */
+export function applyVars(text, vars) {
+  return text.replace(/\{\{([A-Z_]+)\}\}/g, (match, key) =>
+    key in vars ? vars[key] : match,
+  );
+}
+
+/**
+ * Copies a template folder into `dest`, replacing `{{TOKENS}}` in text files.
+ * Existing files are kept (never clobbered) unless `overwrite` is true.
+ * Returns the list of project-relative paths that were written and skipped.
+ */
+export function copyTemplateDir(src, dest, vars, { overwrite = true } = {}) {
+  const written = [];
+  const skipped = [];
+
+  const walk = (from, to) => {
+    fs.mkdirSync(to, { recursive: true });
+    for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+      if (entry.isDirectory() && SKIP_DIRS.has(entry.name)) continue;
+      const source = path.join(from, entry.name);
+      const target = path.join(to, RENAMES[entry.name] ?? entry.name);
+
+      if (entry.isDirectory()) {
+        walk(source, target);
+        continue;
+      }
+
+      const relative = path.relative(dest, target);
+      if (!overwrite && fs.existsSync(target)) {
+        skipped.push(relative);
+        continue;
+      }
+
+      const buffer = fs.readFileSync(source);
+      if (isBinary(buffer)) {
+        fs.writeFileSync(target, buffer);
+      } else {
+        fs.writeFileSync(target, applyVars(buffer.toString('utf8'), vars));
+      }
+      written.push(relative);
+    }
+  };
+
+  walk(src, dest);
+  return { written, skipped };
+}
+
+const sortKeys = (object = {}) =>
+  Object.fromEntries(Object.entries(object).sort(([a], [b]) => a.localeCompare(b)));
+
+/** Merges dependencies / devDependencies / scripts into the project's package.json. */
+export function mergePackageJson(projectDir, patch) {
+  const file = path.join(projectDir, 'package.json');
+  const pkg = JSON.parse(fs.readFileSync(file, 'utf8'));
+
+  for (const key of ['dependencies', 'devDependencies']) {
+    if (patch[key]) pkg[key] = sortKeys({ ...pkg[key], ...patch[key] });
+  }
+  if (patch.scripts) pkg.scripts = { ...pkg.scripts, ...patch.scripts };
+
+  fs.writeFileSync(file, `${JSON.stringify(pkg, null, 2)}\n`);
+}
+
+/**
+ * Inserts `lines` right above the line that contains `marker`, keeping the marker so more
+ * code can be injected later (e.g. `create-my-stack add redis`). The inserted block takes
+ * the marker's indentation. Returns false when the file or the marker is missing.
+ */
+export function injectAtMarker(file, marker, lines) {
+  if (!fs.existsSync(file)) return false;
+  const text = fs.readFileSync(file, 'utf8');
+  const eol = text.includes('\r\n') ? '\r\n' : '\n';
+  const escaped = marker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = new RegExp(`^([ \\t]*)${escaped}.*$`, 'm').exec(text);
+  if (!match) return false;
+
+  const indent = match[1];
+  const block = lines.map((line) => (line === '' ? '' : indent + line)).join(eol);
+  const updated = `${text.slice(0, match.index)}${block}${eol}${text.slice(match.index)}`;
+  fs.writeFileSync(file, updated);
+  return true;
+}
+
+export function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+export function writeJson(file, data) {
+  fs.writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`);
+}
+
+export function appendLines(file, lines) {
+  const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  const prefix = existing === '' || existing.endsWith('\n') ? '' : '\n';
+  fs.writeFileSync(file, `${existing}${prefix}${lines.join('\n')}\n`);
+}

package/lib/registry.mjs

@@ -0,0 +1,50 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readJson } from './fs-utils.mjs';
+
+export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+export const TEMPLATES_DIR = path.join(ROOT, 'templates');
+export const INFRA_DIR = path.join(ROOT, 'infra');
+
+function loadAll(baseDir, manifestName) {
+  if (!fs.existsSync(baseDir)) return [];
+  return fs
+    .readdirSync(baseDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => {
+      const dir = path.join(baseDir, entry.name);
+      const manifest = path.join(dir, manifestName);
+      if (!fs.existsSync(manifest)) return null;
+      return { ...readJson(manifest), dir };
+    })
+    .filter(Boolean);
+}
+
+/** Every template under `templates/`, described by its `template.json`. */
+export const loadTemplates = () => loadAll(TEMPLATES_DIR, 'template.json');
+
+/** Every infra module under `infra/`, described by its `infra.json`. */
+export const loadInfra = () => loadAll(INFRA_DIR, 'infra.json');
+
+/**
+ * Expands the requested infra ids with everything they `require`
+ * (e.g. email -> rabbitmq), preserving order and removing duplicates.
+ */
+export function resolveInfra(requested, available) {
+  const byId = new Map(available.map((infra) => [infra.id, infra]));
+  const ordered = [];
+  const added = [];
+
+  const visit = (id, parent) => {
+    const infra = byId.get(id);
+    if (!infra) throw new Error(`Unknown infra "${id}". Run "list" to see what exists.`);
+    if (ordered.some((item) => item.id === id)) return;
+    for (const dependency of infra.requires ?? []) visit(dependency, id);
+    ordered.push(infra);
+    if (!requested.includes(id)) added.push({ id, because: parent });
+  };
+
+  for (const id of requested) visit(id);
+  return { ordered, added };
+}