@appweaver/cli 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/start/index.d.ts

@@ -0,0 +1,2 @@
+export * from './start-command';
+export * from './start-project';

package/start/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./start-command"), exports);
+__exportStar(require("./start-project"), exports);

package/start/start-command.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function startCommand(program: Command): void;

package/start/start-command.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startCommand = startCommand;
+const start_project_1 = require("./start-project");
+function startCommand(program) {
+    program
+        .command('start')
+        .alias('s')
+        .description('Start the application.')
+        .option('-p, --project [path]', 'TypeScript project config file.', 'tsconfig.build.json')
+        .option('-w, --watch', 'Run in watch mode.')
+        .action(async (_, command) => {
+        const projectFile = command.getOptionValue('project');
+        const watch = command.getOptionValue('watch');
+        await (0, start_project_1.startProject)(projectFile, watch);
+    });
+}

package/start/start-project.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Starts the project using the specified project file and runtime options.
+ *
+ * @param {string} projectFile - The path to the project file that should be used.
+ * @param {boolean} watch - A flag indicating whether to enable watch mode for automatic restarts on file changes.
+ * @return {Promise<void>} A promise that resolves when the project has started.
+ */
+export declare function startProject(projectFile: string, watch: boolean): Promise<void>;

package/start/start-project.js

@@ -0,0 +1,147 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startProject = startProject;
+const node_path_1 = __importDefault(require("node:path"));
+const promises_1 = require("node:fs/promises");
+const client_1 = require("tsc-watch/client");
+const tsc_alias_1 = require("tsc-alias");
+const common_1 = require("@appweaver/common");
+const utils_1 = require("../utils");
+/**
+ * Starts the project using the specified project file and runtime options.
+ *
+ * @param {string} projectFile - The path to the project file that should be used.
+ * @param {boolean} watch - A flag indicating whether to enable watch mode for automatic restarts on file changes.
+ * @return {Promise<void>} A promise that resolves when the project has started.
+ */
+async function startProject(projectFile, watch) {
+    const mainFilePath = node_path_1.default.join(common_1.config.APP_BUILD_PATH, common_1.config.APP_MAIN_FILE_PATH.replace(/\.ts$/i, '.js'));
+    if ((0, utils_1.isBunProcess)() && common_1.config.APP_RUNTIME === common_1.Runtime.Bun) {
+        await startBunProject(mainFilePath, watch);
+    }
+    else {
+        await startNodeProject(mainFilePath, projectFile, watch);
+    }
+}
+/**
+ * Starts a Node.js project by executing the specified main file.
+ * Optionally enables watch mode to monitor file changes.
+ *
+ * @param {string} mainFilePath - The path to the main file to be executed.
+ * @param {string} projectFile - The project configuration file used during execution.
+ * @param {boolean} watch - Whether to enable watch mode for file changes.
+ * @return {Promise<void>} A promise that resolves when the operation completes.
+ */
+async function startNodeProject(mainFilePath, projectFile, watch) {
+    if (watch) {
+        await watchNodeProject(mainFilePath, projectFile);
+    }
+    else {
+        await (0, utils_1.runProcess)('node', [mainFilePath]);
+    }
+}
+/**
+ * Starts a Bun project by running the specified main file. Optionally enables a watch mode.
+ *
+ * @param {string} mainFilePath - The path to the main file to run with Bun.
+ * @param {boolean} watch - Determines whether the Bun process should execute in watch mode.
+ * @return {Promise<void>} A promise that resolves when the Bun process starts or when the watch mode is initiated.
+ */
+async function startBunProject(mainFilePath, watch) {
+    if (watch) {
+        await watchBunProcess();
+    }
+    else {
+        await (0, utils_1.runProcess)('bun', [mainFilePath]);
+    }
+}
+/**
+ * Watches the specified Node.js project for changes, recompiles TypeScript files, replaces aliases in import patsh,
+ * and restarts the main application process upon successful compilation.
+ *
+ * @param {string} mainFilePath - The entry point of the application that will be executed after each successful
+ * compilation.
+ * @param {string} projectFile - The TypeScript config file path (tsconfig.json).
+ * @return {Promise<void>} A promise that resolves when the watching process is stopped.
+ */
+async function watchNodeProject(mainFilePath, projectFile) {
+    let abortController;
+    const watch = new client_1.TscWatchClient();
+    // Handler for every successful compilation of watched code, aborts previous
+    // process and starts a new one
+    watch.on('success', async () => {
+        if (abortController) {
+            abortController.abort();
+        }
+        abortController = new AbortController();
+        // Replace import alias paths in compiled code
+        await (0, tsc_alias_1.replaceTscAliasPaths)({ configFile: projectFile });
+        // Start the main application process
+        await (0, utils_1.runProcess)('node', [mainFilePath], {
+            signal: abortController.signal
+        });
+    });
+    // Handler for any compilation error to abort previously started process
+    watch.on('compile_errors', () => {
+        abortController?.abort();
+    });
+    // Cleanup should be done only once on process termination
+    let cleanedUp = false;
+    const cleanup = () => {
+        if (cleanedUp) {
+            return;
+        }
+        cleanedUp = true;
+        abortController?.abort();
+        watch.kill();
+    };
+    // When process is terminated in any way, all processes should be aborted
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
+    process.on('exit', cleanup);
+    watch.start('-p', projectFile);
+}
+/**
+ * Monitors file changes in the specified directory and restarts the Bun process accordingly.
+ * The function uses a debounced mechanism to prevent restarting the process too frequently.
+ * Debounce threshold is 200 milliseconds.
+ *
+ * @return {Promise<void>} A promise that resolves when the watching process is stopped.
+ */
+async function watchBunProcess() {
+    let abortController;
+    let debounceTimer;
+    // Starts a new process and aborts the previous one
+    async function start() {
+        if (abortController) {
+            abortController.abort();
+        }
+        abortController = new AbortController();
+        await (0, utils_1.runProcess)('bun', [common_1.config.APP_MAIN_FILE_PATH], {
+            signal: abortController.signal
+        });
+    }
+    // Initially start the application process
+    start().catch((err) => {
+        console.error(err);
+        process.exit(1);
+    });
+    // Wait before starting watcher to prevent restarts during init phase
+    await new Promise((r) => setTimeout(r, 200));
+    // Watch for file changes and start new process using debounce timer
+    for await (const info of (0, promises_1.watch)(common_1.config.APP_SOURCE_PATH, { recursive: true })) {
+        if (info.filename === null) {
+            // Skip non-file change events
+            continue;
+        }
+        if (debounceTimer) {
+            clearTimeout(debounceTimer);
+        }
+        debounceTimer = setTimeout(async () => {
+            await start();
+        }, 100);
+    }
+}

package/testing/index.d.ts

@@ -0,0 +1 @@
+export * from './testing-command';

package/testing/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./testing-command"), exports);

package/testing/testing-command.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function testingCommand(program: Command): void;

package/testing/testing-command.js

@@ -0,0 +1,96 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.testingCommand = testingCommand;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const common_1 = require("@appweaver/common");
+const generate_1 = require("../generate");
+const utils_1 = require("../utils");
+function testingCommand(program) {
+    const testCommand = program
+        .command('test')
+        .alias('t')
+        .description('Perform operations used during testing.');
+    testCommand
+        .command('setup')
+        .description('Setup temporary test data (database schema and migrations).')
+        .option('-d, --dir [tempDir]', 'Directory used by tests to store temporary data.', './temp')
+        .option('--modelPattern [pattern]', 'Glob pattern for finding model files. (default: from config or env).')
+        .option('--schemaPath [path]', 'Output path for generated Prisma schema. (default: from config or env).')
+        .option('--clientPath [path]', 'Output path for generated Prisma client (default: from config or env).')
+        .option('--migrationName [name]', 'Name for the new migration.', 'init_test')
+        .option('--verbose', 'Print verbose output.')
+        .action(async (_, command) => {
+        (0, utils_1.assertEnv)('test', '"weaver test setup" must be started in "test" environment (NODE_ENV=test).');
+        const quiet = !command.getOptionValue('verbose');
+        const tempDir = command.getOptionValue('dir');
+        const storagePath = common_1.config.STORAGE_PATH;
+        const schemaPath = command.getOptionValue('schemaPath') ?? common_1.config.DATABASE_SCHEMA_PATH;
+        const clientPath = command.getOptionValue('clientPath') ??
+            common_1.config.DATABASE_CLIENT_OUTPUT_DIR_PATH;
+        (0, utils_1.assertPathInside)(tempDir, storagePath, `Storage path must be inside temp directory: ${tempDir}`);
+        (0, utils_1.assertPathInside)(tempDir, schemaPath, `Schema path must be inside temp directory: ${tempDir}`);
+        (0, utils_1.assertPathInside)(tempDir, clientPath, `Client output path must be inside temp directory: ${tempDir}`);
+        await (0, utils_1.rimrafPath)(tempDir, quiet);
+        await promises_1.default.mkdir(storagePath, { recursive: true });
+        console.log('Storage initialized');
+        const models = await (0, utils_1.loadModels)(command.getOptionValue('modelPattern') ?? common_1.config.RESOURCE_MODEL_PATTERN);
+        const generateStatus = await (0, generate_1.generateSchema)(models, schemaPath, clientPath, quiet);
+        if (generateStatus !== 0) {
+            console.error('Failed to generate Prisma schema');
+            process.exit(generateStatus);
+        }
+        const migrateStatus = await (0, utils_1.runProcess)('prisma', ['migrate', 'dev', '--name', command.getOptionValue('migrationName')], { quiet });
+        if (migrateStatus !== 0) {
+            console.error('Failed to generate new migration');
+            process.exit(migrateStatus);
+        }
+        console.log('Database initialized');
+    });
+    testCommand
+        .command('reset')
+        .description('Reset database and/or file storage in temporary directory.')
+        .option('-d, --dir [tempDir]', 'Directory used by tests to store temporary data.', './temp')
+        .option('--database', 'Reset database content.')
+        .option('--storage', 'Reset storage files.')
+        .option('--verbose', 'Print verbose output.')
+        .action(async (_, command) => {
+        (0, utils_1.assertEnv)('test', '"weaver test reset" must be started in "test" environment (NODE_ENV=test).');
+        const quiet = !command.getOptionValue('verbose');
+        const tempDir = command.getOptionValue('dir');
+        const storagePath = common_1.config.STORAGE_PATH;
+        (0, utils_1.assertPathInside)(tempDir, storagePath, `Storage path must be inside temp directory: ${tempDir}`);
+        const resetAll = !command.getOptionValue('database') &&
+            !command.getOptionValue('storage');
+        if (command.getOptionValue('database') || resetAll) {
+            const migrateStatus = await (0, utils_1.runProcess)('prisma', ['migrate', 'reset', '-f'], { quiet });
+            if (migrateStatus !== 0) {
+                console.error('Failed to migrate database');
+                process.exit(migrateStatus);
+            }
+            console.log('Database reset');
+        }
+        if (command.getOptionValue('storage') || resetAll) {
+            const result = await (0, utils_1.rimrafPath)(storagePath, quiet);
+            if (result) {
+                console.log('Storage cleared');
+            }
+        }
+    });
+    testCommand
+        .command('teardown')
+        .description('Remove temporary test directory.')
+        .option('-d, --dir [tempDir]', 'Directory used by tests to store temporary data.', './temp')
+        .option('--verbose', 'Print verbose output.')
+        .action(async (_, command) => {
+        (0, utils_1.assertEnv)('test', '"weaver test teardown" must be started in "test" environment (NODE_ENV=test).');
+        const quiet = !command.getOptionValue('verbose');
+        const tempDir = command.getOptionValue('dir');
+        const result = await (0, utils_1.rimrafPath)(tempDir, quiet);
+        if (result) {
+            console.log(`Removed temporary directory ${tempDir}`);
+        }
+    });
+}

package/update/index.d.ts

@@ -0,0 +1,2 @@
+export * from './update-command';
+export * from './update-packages';

package/update/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./update-command"), exports);
+__exportStar(require("./update-packages"), exports);

package/update/update-command.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function updateCommand(program: Command): void;