@appweaver/create-weaver-app 1.0.0

package/skill/references/storage.md

@@ -0,0 +1,251 @@
+# Storage
+
+The storage module handles file persistence: storing, streaming, and deleting binary content. The default
+implementation (`FilesystemStorage`) writes files to a local directory using a configurable name pattern. The module
+supports range-based streaming for efficient large-file delivery (e.g., video, audio).
+
+## Injecting Storage
+
+```ts
+import { inject } from '@appweaver/core';
+import { Storage } from '@appweaver/common';
+
+const storage = inject(Storage);
+```
+
+---
+
+#### `storage.store(fileName, data)`
+
+Persists a readable stream under the given file name. Returns the stored file's path/ID (derived from
+`STORAGE_NAME_PATTERN`), or `null` on failure.
+
+| Parameter  | Type       | Description                                |
+|------------|------------|--------------------------------------------|
+| `fileName` | `string`   | Original file name (used for name pattern) |
+| `data`     | `Readable` | Node.js readable stream with the content   |
+
+```ts
+import { createReadStream } from 'node:fs';
+
+const fileId = await storage.store('avatar.png', createReadStream('/tmp/upload.png'));
+// fileId e.g. "avatar-a3f8bc12.png"
+```
+
+**From a multipart upload (Fastify example):**
+
+```ts
+const upload = await req.file();
+const fileId = await storage.store(upload.filename, upload.file);
+```
+
+---
+
+#### `storage.stream(fileName, start, end?)`
+
+Returns a `ContentStream` for the stored file, or `null` if the file does not exist. Supports range requests.
+
+| Parameter  | Type     | Description                                |
+|------------|----------|--------------------------------------------|
+| `fileName` | `string` | File ID returned by `store`                |
+| `start`    | `number` | Byte offset to start reading from          |
+| `end`      | `number` | Byte offset to stop reading at (inclusive) |
+
+```ts
+type ContentStream = {
+  stream: Readable;
+  size: number;     // total file size in bytes
+};
+```
+
+**Full file download:**
+
+```ts
+const result = await storage.stream('avatar-a3f8bc12.png', 0);
+if (!result) throw new Error('File not found');
+
+reply.header('Content-Length', result.size);
+reply.send(result.stream);
+```
+
+**Range request (e.g., video seeking):**
+
+```ts
+const { start, end } = parseRangeHeader(req.headers.range, fileSize);
+const result = await storage.stream(fileId, start, end);
+
+reply
+  .status(206)
+  .header('Content-Range', `bytes ${start}-${end}/${fileSize}`)
+  .send(result.stream);
+```
+
+---
+
+#### `storage.exists(fileName)`
+
+Returns `true` if the file exists in storage.
+
+```ts
+if (await storage.exists('avatar-a3f8bc12.png')) {
+  // safe to stream
+}
+```
+
+---
+
+#### `storage.delete(fileName)`
+
+Deletes the stored file. Returns `true` if the file existed and was removed.
+
+```ts
+await storage.delete('avatar-a3f8bc12.png');
+```
+
+---
+
+#### `storage.checkHealth()`
+
+Verifies that the storage directory is readable and writable. Returns a `HealthCheckResult`.
+
+---
+
+## File name pattern
+
+Stored files are renamed according to `STORAGE_NAME_PATTERN`. The default pattern is `{name}-{hash}.{extension}`, which
+produces collision-resistant names while preserving the original extension.
+
+Available placeholders:
+
+| Placeholder   | Resolved to                 |
+|---------------|-----------------------------|
+| `{name}`      | Base name without extension |
+| `{hash}`      | Short content hash          |
+| `{extension}` | Original file extension     |
+
+Example: storing `photo.jpg` produces `photo-c7d3a1f2.jpg`.
+
+---
+
+## Configuration
+
+| Key                          | Type     | Default                                        | Description                                           |
+|------------------------------|----------|------------------------------------------------|-------------------------------------------------------|
+| `STORAGE_PATH`               | `string` | `'./storage'`                                  | Root directory where files are stored                 |
+| `STORAGE_NAME_PATTERN`       | `string` | `'{name}-{hash}.{extension}'`                  | Template for deriving the stored file name            |
+| `STORAGE_CACHE_TTL`          | `int`    | `86400000`                                     | Cache TTL for storage responses in milliseconds (24h) |
+| `STORAGE_FILES_ROUTE_PREFIX` | `string` | `/files`                                       | URL prefix for file access routes.                    |
+| `STORAGE_PROVIDER`           | `string` | `'@appweaver/core/storage/filesystem-storage'` | Path to the Storage implementation                    |
+
+**`appweaver.json` example:**
+
+```json
+{
+  "STORAGE_PATH": "./uploads",
+  "STORAGE_NAME_PATTERN": "{name}-{hash}.{extension}"
+}
+```
+
+---
+
+## Real-world example
+
+```ts
+import { inject } from '@appweaver/core';
+import { Storage } from '@appweaver/common';
+
+export class AvatarService {
+  private readonly _storage = inject(Storage);
+
+  async upload(userId: number, stream: Readable, originalName: string): Promise<string> {
+    const fileId = await this._storage.store(originalName, stream);
+    if (!fileId) throw new Error('Upload failed');
+
+    await saveAvatarRecord(userId, fileId);
+    return fileId;
+  }
+
+  async download(fileId: string): Promise<{ stream: Readable; size: number }> {
+    const result = await this._storage.stream(fileId, 0);
+    if (!result) throw new Error('File not found');
+    return result;
+  }
+
+  async remove(fileId: string): Promise<void> {
+    await this._storage.delete(fileId);
+    await deleteAvatarRecord(fileId);
+  }
+}
+```
+
+---
+
+## FileService usage
+
+The `FileService` provides higher-level file management specifically for **Resource Models**. Unlike the raw `Storage`
+module, it automatically manages the database records (`File` entries) and enforces security policies defined on your
+models.
+
+### Injecting FileService
+
+```ts
+import { inject } from '@appweaver/core';
+import { FileService } from '@appweaver/core/storage';
+
+const fileService = inject(FileService);
+```
+
+### Saving a file
+
+When saving a file via `FileService`, you must provide the multipart data, the resource instance it belongs to, and its
+`ResourceClient`.
+
+```ts
+import { inject, injectService, injectModel } from '@appweaver/core';
+import { FileService } from '@appweaver/core/storage';
+
+export class PostService {
+  private readonly _fileService = inject(FileService);
+  private readonly _postService = injectService('Post');
+  private readonly _postClient = injectModel('Post');
+
+  async uploadImage(postId: number, data: MultipartFile) {
+    const post = await this._postService.find(postId);
+
+    // saveFile stores the file in Storage AND creates a File record in the DB
+    // linked to the 'image' field of the 'post' resource.
+    const file = await this._fileService.saveFile(data, post, this._postClient);
+
+    return file;
+  }
+}
+```
+
+### Streaming a file
+
+`FileService.stream()` handles authorization checks (public, private, or protected) and range-based requests
+automatically.
+
+```ts
+// Streams a file while checking if the current user has access
+const fileStream = await fileService.stream('photo-c7d3a1f2.jpg', req.headers.range);
+
+reply
+  .status(fileStream.start > 0 ? 206 : 200)
+  .header('Content-Type', fileStream.mimeType)
+  .header('Content-Disposition', `attachment; filename="${fileStream.fileName}"`)
+  .send(fileStream.content.stream);
+```
+
+### Deleting a file
+
+Deleting a file via `FileService` removes it from both the storage backend and the database.
+
+```ts
+await fileService.deleteFile(
+  'photo-c7d3a1f2.jpg',
+  'image', // resource field name
+  post,    // resource instance
+  postClient // ResourceClient
+);
+```

package/templates/default/.dockerignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+storage
+logs
+.env

package/templates/default/.env.tpl

@@ -0,0 +1 @@
+NODE_ENV=dev

package/templates/default/.prettierignore

@@ -0,0 +1,3 @@
+**/dist
+**/node_modules
+**/database/client

package/templates/default/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "endOfLine": "lf",
+  "singleQuote": true,
+  "trailingComma": "none",
+  "tabWidth": 2,
+  "printWidth": 80
+}

package/templates/default/Dockerfile

@@ -0,0 +1,56 @@
+## 1. Install dependencies and build the application
+FROM node:24.13.0-alpine AS build
+
+# Install tools for building libraries on other platforms
+RUN apk add build-base python3 py3-pip make gcc
+
+# Create app directory
+WORKDIR /usr/app
+
+# Copy project files
+COPY ../.. .
+
+# Install NPM dependencies
+RUN npm ci
+
+# Build project
+RUN npm run build
+
+
+## 2. Setup server environment, copy build output and start the application script
+FROM node:24.13.0-alpine AS deploy
+
+# Install tools for building libraries on other platforms
+RUN apk add build-base python3 py3-pip make gcc
+
+# Create app directory
+WORKDIR /usr/app
+
+# Copy NPM package
+COPY --from=build /usr/app/package*.json /usr/app/
+
+# Install NPM dependencies for production
+RUN npm ci --omit=dev
+
+# Copy build files
+COPY --from=build /usr/app/dist /usr/app/dist
+
+# Copy Prisma config, database migrations, and schema file
+COPY --from=build /usr/app/prisma.config.ts /usr/app/prisma.config.ts
+COPY --from=build /usr/app/database/migrations /usr/app/database/migrations
+COPY --from=build /usr/app/database/schema.prisma /usr/app/database/schema.prisma
+
+# Copy config file/s
+COPY --from=build /usr/app/appweaver*.json /usr/app/
+
+# Copy start script
+COPY --from=build /usr/app/start.sh /usr/app/start.sh
+
+# Make start script executable
+RUN chmod +x /usr/app/start.sh
+
+# Create storage and logs directories
+RUN mkdir storage logs
+
+# Start container
+ENTRYPOINT ["/usr/app/start.sh"]

package/templates/default/Dockerfile.bun

@@ -0,0 +1,56 @@
+## 1. Install dependencies and build the application
+FROM oven/bun:1.3.11-alpine AS build
+
+# Install tools for building libraries on other platforms
+RUN apk add build-base python3 py3-pip make gcc
+
+# Create app directory
+WORKDIR /usr/app
+
+# Copy project files
+COPY ../.. .
+
+# Install NPM dependencies
+RUN bun install --frozen-lockfile
+
+# Build project
+RUN bun run build
+
+
+## 2. Setup server environment, copy build output and start the application script
+FROM oven/bun:1.3.11-alpine AS deploy
+
+# Install tools for building libraries on other platforms
+RUN apk add build-base python3 py3-pip make gcc
+
+# Create app directory
+WORKDIR /usr/app
+
+# Copy NPM package
+COPY --from=build /usr/app/package*.json /usr/app/
+
+# Install NPM dependencies for production
+RUN bun install --frozen-lockfile --production
+
+# Copy build files
+COPY --from=build /usr/app/dist /usr/app/dist
+
+# Copy Prisma config, database migrations, and schema file
+COPY --from=build /usr/app/prisma.config.ts /usr/app/prisma.config.ts
+COPY --from=build /usr/app/database/migrations /usr/app/database/migrations
+COPY --from=build /usr/app/database/schema.prisma /usr/app/database/schema.prisma
+
+# Copy config file/s
+COPY --from=build /usr/app/appweaver*.json /usr/app/
+
+# Copy start script
+COPY --from=build /usr/app/start.sh /usr/app/start.sh
+
+# Make start script executable
+RUN chmod +x /usr/app/start.sh
+
+# Create storage and logs directories
+RUN mkdir storage logs
+
+# Start container
+ENTRYPOINT ["/usr/app/start.sh"]

package/templates/default/README.md.tpl

@@ -0,0 +1,7 @@
+# {{NAME}}
+
+> {{DESCRIPTION}}
+
+## License
+
+UNLICENSED

package/templates/default/appweaver.dev.json.tpl

@@ -0,0 +1,9 @@
+{
+  "$schema": "./node_modules/@appweaver/common/config/schema.json",
+  "config": {
+    "log": {
+      "level": "debug",
+      "pretty": true
+    }
+  }
+}

package/templates/default/appweaver.json.bun.tpl

@@ -0,0 +1,17 @@
+{
+  "$schema": "./node_modules/@appweaver/common/config/schema.json",
+  "config": {
+    "app": {
+      "name": "{{NAME}}",
+      "description": "{{DESCRIPTION}}",
+      "runtime": "bun"
+    },
+    "server": {
+      "host": "{{HOST}}",
+      "port": {{PORT}}
+    },
+    "database": {
+      "url": "{{DATABASE_URL}}"
+    }
+  }
+}

package/templates/default/appweaver.json.tpl

@@ -0,0 +1,16 @@
+{
+  "$schema": "./node_modules/@appweaver/common/config/schema.json",
+  "config": {
+    "app": {
+      "name": "{{NAME}}",
+      "description": "{{DESCRIPTION}}"
+    },
+    "server": {
+      "host": "{{HOST}}",
+      "port": {{PORT}}
+    },
+    "database": {
+      "url": "{{DATABASE_URL}}"
+    }
+  }
+}

package/templates/default/appweaver.test.json.tpl

@@ -0,0 +1,30 @@
+{
+  "$schema": "./node_modules/@appweaver/common/config/schema.json",
+  "config": {
+    "log": {
+      "level": "error",
+      "pretty": true
+    },
+    "database": {
+      "url": "{{DATABASE_TEST_URL}}",
+      "schemaPath": "./temp/database/schema.prisma",
+      "migrationsDirPath": "./temp/database/migrations",
+      "clientOutputDirPath": "./temp/database/client"
+    },
+    "storage": {
+      "path": "./temp/storage"
+    },
+    "redis": {
+      "provider": "@appweaver/core/memory/in-memory"
+    },
+    "queue": {
+      "provider": "@appweaver/core/queue/memory-queue"
+    },
+    "mailer": {
+      "provider": "@appweaver/core/mailer/json-mailer"
+    },
+    "scheduler": {
+      "autoStartJob": false
+    }
+  }
+}

package/templates/default/bunfig.toml.bun

@@ -0,0 +1,8 @@
+[install]
+linker = "isolated"
+
+[test]
+root = "test"
+coverageReporter = ["text", "lcov"]
+coverageSkipTestFiles = true
+coverageDir = "./reports"

package/templates/default/database/client.ts.tpl

@@ -0,0 +1,7 @@
+import { inject } from '@appweaver/core';
+import { Database } from '@appweaver/common';
+import { PrismaClient } from '@db/client/client';
+
+export const db = inject(Database).client<PrismaClient>();
+
+export default db;

package/templates/default/database/schema.prisma

@@ -0,0 +1,13 @@
+// This is your Prisma schema file,
+// learn more about it in the docs: https://pris.ly/d/prisma-schema
+
+// Generated by Appweaver. Please do not edit this file manually.
+
+datasource db {
+  provider = "sqlite"
+}
+
+generator client {
+  provider = "prisma-client"
+  output   = "./client"
+}

package/templates/default/database/seeders/001-create-admin-user.ts.tpl

@@ -0,0 +1,39 @@
+import { hashPassword } from '@appweaver/core';
+import { config, randomString } from '@appweaver/common';
+import { db } from '@db/client';
+
+export async function createAdminUser(): Promise<void> {
+  let password = config.SYSTEM_ADMIN_INITIAL_PASSWORD;
+
+  if (!password) {
+    password = randomString(16, { extra: false });
+    console.log(`Generated admin password: ${password}`);
+  }
+
+  const passwordHash = await hashPassword(password);
+
+  await db.user.create({
+    data: {
+      firstName: 'Admin',
+      lastName: 'Admin',
+      email: config.SYSTEM_ADMIN_INITIAL_EMAIL,
+      passwordHash,
+      roles: {
+        connectOrCreate: [
+          {
+            where: { name: 'Admin' },
+            create: {
+              name: 'Admin',
+              permissions: {
+                connectOrCreate: [
+                  { where: { name: '*.read' }, create: { name: '*.read' } },
+                  { where: { name: '*.write' }, create: { name: '*.write' } }
+                ]
+              }
+            }
+          }
+        ]
+      }
+    }
+  });
+}

package/templates/default/eslint.config.mjs

@@ -0,0 +1,55 @@
+import eslint from '@eslint/js';
+import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
+import eslintPluginJest from 'eslint-plugin-jest';
+import globals from 'globals';
+import tsEslint from 'typescript-eslint';
+
+export default tsEslint.config(
+  {
+    ignores: [
+      'node_modules',
+      'dist',
+      'database/client',
+      '**/*.js',
+      '**/*.d.ts'
+    ]
+  },
+  eslint.configs.recommended,
+  ...tsEslint.configs.recommendedTypeChecked.map((config) => ({ ...config })),
+  eslintPluginPrettierRecommended,
+  eslintPluginJest.configs['flat/recommended'],
+  {
+    languageOptions: {
+      globals: {
+        ...globals.node,
+        ...globals.jest
+      },
+      ecmaVersion: 5,
+      sourceType: 'module',
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname
+      }
+    }
+  },
+  {
+    rules: {
+      '@typescript-eslint/interface-name-prefix': 'off',
+      '@typescript-eslint/explicit-function-return-type': 'off',
+      '@typescript-eslint/explicit-module-boundary-types': 'off',
+      '@typescript-eslint/restrict-template-expressions': 'off',
+      '@typescript-eslint/require-await': 'off',
+      '@typescript-eslint/unbound-method': 'off',
+      '@typescript-eslint/no-redundant-type-constituents': 'off',
+      '@typescript-eslint/no-misused-promises': 'off',
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-empty-object-type': 'off',
+      '@typescript-eslint/no-unused-vars': 'off',
+      '@typescript-eslint/no-unsafe-member-access': 'off',
+      '@typescript-eslint/no-unsafe-assignment': 'off',
+      '@typescript-eslint/no-unsafe-argument': 'off',
+      '@typescript-eslint/no-unsafe-call': 'off',
+      '@typescript-eslint/no-unsafe-return': 'off'
+    }
+  }
+);

package/templates/default/eslint.config.mjs.bun

@@ -0,0 +1,53 @@
+import eslint from '@eslint/js';
+import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
+import globals from 'globals';
+import tsEslint from 'typescript-eslint';
+
+export default tsEslint.config(
+  {
+    ignores: [
+      'node_modules',
+      'dist',
+      'database/client',
+      '**/*.js',
+      '**/*.d.ts'
+    ]
+  },
+  eslint.configs.recommended,
+  ...tsEslint.configs.recommendedTypeChecked.map((config) => ({ ...config })),
+  eslintPluginPrettierRecommended,
+  {
+    languageOptions: {
+      globals: {
+        ...globals.node,
+        ...globals.bunBuiltin
+      },
+      ecmaVersion: 5,
+      sourceType: 'module',
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname
+      }
+    }
+  },
+  {
+    rules: {
+      '@typescript-eslint/interface-name-prefix': 'off',
+      '@typescript-eslint/explicit-function-return-type': 'off',
+      '@typescript-eslint/explicit-module-boundary-types': 'off',
+      '@typescript-eslint/restrict-template-expressions': 'off',
+      '@typescript-eslint/require-await': 'off',
+      '@typescript-eslint/unbound-method': 'off',
+      '@typescript-eslint/no-redundant-type-constituents': 'off',
+      '@typescript-eslint/no-misused-promises': 'off',
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-empty-object-type': 'off',
+      '@typescript-eslint/no-unused-vars': 'off',
+      '@typescript-eslint/no-unsafe-member-access': 'off',
+      '@typescript-eslint/no-unsafe-assignment': 'off',
+      '@typescript-eslint/no-unsafe-argument': 'off',
+      '@typescript-eslint/no-unsafe-call': 'off',
+      '@typescript-eslint/no-unsafe-return': 'off'
+    }
+  }
+);

package/templates/default/jest.config.json.node

@@ -0,0 +1,23 @@
+{
+  "moduleFileExtensions": ["js", "json", "ts"],
+  "rootDir": ".",
+  "testEnvironment": "node",
+  "testMatch": ["**/?(*.)+(spec|test).ts"],
+  "testPathIgnorePatterns": ["/test/e2e/"],
+  "transform": {
+    "^.+\\.(t|j)s$": ["@swc/jest"]
+  },
+  "reporters": [
+    "default",
+    [
+      "jest-junit",
+      {
+        "outputDirectory": "./reports",
+        "outputName": "junit.xml"
+      }
+    ]
+  ],
+  "coverageReporters": ["cobertura", "text"],
+  "collectCoverageFrom": ["./src/**/*.(t|j)s"],
+  "coverageDirectory": "./reports"
+}