libmodulor 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # CHANGELOG
 
+## v0.9.0 (2025-03-20)
+
+**BREAKING**
+
+- Move `bindServer` to `libmodulor/node-express`. The following dependencies (`jose`) are now optional. You can remove them if you're using `libmodulor/node` elements in non server targets like `cli`
+- Upgrade to `fast-check` [v4](https://fast-check.dev/docs/migration-guide/from-3.x-to-4.x) : Re-generate your tests with `yarn libmodulor GenerateAppsTests` to get the changes adapted to this version
+
+**Misc**
+
+- Make `buffer`, `fast-check` and `vitest` deps optional : basic uses of `libmodulor` do not require them (see https://libmodulor.c100k.eu/docs/examples/Basic as an example). You can remove them if you're not using the automated tests
+- Add `ListOrdersUCD` an `CancelOrderUCD` to `examples/supertrader` to showcase data fetching, aggregate building, sensitive use cases, test flows, etc.
+- Remove linter config from examples (linting from repo root folder)
+- Use `debug` instead of `trace` in `ConsoleLogger`
+
+## v0.8.0 (2025-03-13)
+
+**BREAKING**
+
+- Move `NodeExpressServerManager` to a dedicated export (`libmodulor/node` => `libmodulor/node-express`). The following dependencies (`cookie-parser`, `express`, `express-fileupload` and `helmet`) are now optional. You can remove them if you're using `libmodulor/node` elements in non server targets like `cli`
+- Do not enforce `dt` and `policies` folders in app src : place everything that **is not** `*UCD` and `*ServerMain` into `lib` the way you prefer
+- Check app src folder contents : it must contain only the elements allowed by the spec (Re-generate your tests with `yarn libmodulor GenerateAppsTests` to enforce the new rule)
+
+**Misc**
+
+- Introduce new "Basic" example showing all the primitives in action in one single `.ts` file
+- Move `examples/libmodulor-tuto` to `examples/supertrader`
+- Add `llms.txt` to docs at https://libmodulor.c100k.eu/llms.txt
+
 ## v0.7.0 (2025-03-07)
 
 **Added**

package/README.md

@@ -23,4 +23,4 @@ If you think you can help in any way, feel free to contact me (cf. `author` in `
 
 ## ⚖️ License
 
-[LGPL-3.0](https://github.com/c100k/libmodulor/blob/v0.7.0/LICENSE)
+[LGPL-3.0](https://github.com/c100k/libmodulor/blob/v0.9.0/LICENSE)

package/dist/esm/apps/Helper/src/lib/project.js

@@ -42,18 +42,18 @@ export const PACKAGE_JSON = (name) => `{
     },
     "devDependencies": {
         "@biomejs/biome": "^1.9.4",
-        "@types/node": "^22.13.8",
-        "@vitest/coverage-v8": "^3.0.7",
+        "@types/node": "^22.13.10",
+        "@vitest/coverage-v8": "^3.0.8",
         "buffer": "^6.0.3",
         "cookie-parser": "^1.4.7",
         "express": "^4.21.2",
         "express-fileupload": "^1.5.1",
-        "fast-check": "^3.23.2",
+        "fast-check": "^4.0.0",
         "helmet": "^8.0.0",
-        "jose": "^6.0.8",
+        "jose": "^6.0.10",
         "typescript": "^5.8.2",
-        "vite": "^6.2.0",
-        "vitest": "^3.0.7"
+        "vite": "^6.2.2",
+        "vitest": "^3.0.8"
     }
 }
 `;

package/dist/esm/convention.d.ts

@@ -10,12 +10,15 @@ export declare const APP_I18N_FILE_NAME: string;
 export declare const APP_INDEX_NAME: string;
 export declare const APP_INDEX_FILE_NAME: string;
 export declare const APP_INDEX_FILE_NAME_FOR_IMPORT: string;
+export declare const APP_INSTALLER_FILE_NAME: string;
 export declare const APP_MANIFEST_NAME: string;
 export declare const APP_MANIFEST_FILE_EXT: string;
 export declare const APP_MANIFEST_FILE_NAME: string;
 export declare const APP_NAME_PLACEHOLDER: AppName;
 export declare const APP_ROOT_FROM_UCD: string[];
+export declare const APP_SETTINGS_FILE_NAME: string;
 export declare const APP_SRC_DIR_NAME: string;
+export declare const APP_SRC_LIB_DIR_NAME: string;
 export declare const APP_SRC_UCDS_DIR_NAME: string;
 export declare const APP_TEST_DIR_NAME: string;
 export declare const APP_TEST_MAIN_FILE_NAME: string;

package/dist/esm/convention.js

@@ -14,12 +14,15 @@ export const APP_I18N_FILE_NAME = `${APP_I18N_NAME.toLowerCase()}.ts`;
 export const APP_INDEX_NAME = 'index';
 export const APP_INDEX_FILE_NAME = `${APP_INDEX_NAME}.ts`;
 export const APP_INDEX_FILE_NAME_FOR_IMPORT = 'index.js'; // ESM
+export const APP_INSTALLER_FILE_NAME = 'installer.ts';
 export const APP_MANIFEST_NAME = 'Manifest';
 export const APP_MANIFEST_FILE_EXT = '.ts';
 export const APP_MANIFEST_FILE_NAME = `${APP_MANIFEST_NAME.toLowerCase()}${APP_MANIFEST_FILE_EXT}`;
 export const APP_NAME_PLACEHOLDER = 'AppX';
 export const APP_ROOT_FROM_UCD = ['..', '..', '..']; // $root/src/ucds/XyzUCD.ts
+export const APP_SETTINGS_FILE_NAME = 'settings.ts';
 export const APP_SRC_DIR_NAME = SRC_DIR_NAME;
+export const APP_SRC_LIB_DIR_NAME = 'lib';
 export const APP_SRC_UCDS_DIR_NAME = 'ucds';
 export const APP_TEST_DIR_NAME = 'test';
 export const APP_TEST_MAIN_FILE_NAME = 'App.test.ts';

package/dist/esm/index.node-express.d.ts

@@ -0,0 +1,2 @@
+export { NodeExpressServerManager } from './target/node-express-server/NodeExpressServerManager.js';
+export { bindServer } from './utils/ioc/bindServer.js';

package/dist/esm/index.node-express.js

@@ -0,0 +1,2 @@
+export { NodeExpressServerManager } from './target/node-express-server/NodeExpressServerManager.js';
+export { bindServer } from './utils/ioc/bindServer.js';

package/dist/esm/index.node.d.ts

@@ -8,7 +8,5 @@ export { NodeHTTPAPICallExecutorAgentBuilder } from './std/impl/NodeHTTPAPICallE
 export { NodePromptManager } from './std/impl/NodePromptManager.js';
 export { NodeSpawnShellCommandExecutor } from './std/impl/NodeSpawnShellCommandExecutor.js';
 export { NodeCoreCLIManager } from './target/node-core-cli/NodeCoreCLIManager.js';
-export { NodeExpressServerManager } from './target/node-express-server/NodeExpressServerManager.js';
 export { bindNodeCLI } from './utils/ioc/bindNodeCLI.js';
 export { bindNodeCore } from './utils/ioc/bindNodeCore.js';
-export { bindServer } from './utils/ioc/bindServer.js';

package/dist/esm/index.node.js

@@ -8,7 +8,5 @@ export { NodeHTTPAPICallExecutorAgentBuilder } from './std/impl/NodeHTTPAPICallE
 export { NodePromptManager } from './std/impl/NodePromptManager.js';
 export { NodeSpawnShellCommandExecutor } from './std/impl/NodeSpawnShellCommandExecutor.js';
 export { NodeCoreCLIManager } from './target/node-core-cli/NodeCoreCLIManager.js';
-export { NodeExpressServerManager } from './target/node-express-server/NodeExpressServerManager.js';
 export { bindNodeCLI } from './utils/ioc/bindNodeCLI.js';
 export { bindNodeCore } from './utils/ioc/bindNodeCore.js';
-export { bindServer } from './utils/ioc/bindServer.js';

package/dist/esm/index.vite.d.ts

@@ -1 +1 @@
-export { StripUCDLifecycleServerPlugin } from './bundlers/vite/StripUCDLifecycleServerPlugin.js';
+export { StripUCDLifecycleServerPlugin } from './utils/bundling/vite/StripUCDLifecycleServerPlugin.js';

package/dist/esm/index.vite.js

@@ -1 +1 @@
-export { StripUCDLifecycleServerPlugin } from './bundlers/vite/StripUCDLifecycleServerPlugin.js';
+export { StripUCDLifecycleServerPlugin } from './utils/bundling/vite/StripUCDLifecycleServerPlugin.js';

package/dist/esm/std/impl/ConsoleLogger.js

@@ -56,8 +56,9 @@ let ConsoleLogger = class ConsoleLogger {
         if (!this.shouldLog('trace')) {
             return;
         }
+        // Using "debug" instead of "trace" because trace expands the stacktrace and pollutes the logs
         // biome-ignore lint/suspicious/noConsole: we want it
-        console.trace(`${this.t()} [trace] ${message}`, ...meta);
+        console.debug(`${this.t()} [trace] ${message}`, ...meta);
     }
     warn(message, ...meta) {
         if (!this.shouldLog('warn')) {

package/dist/esm/testing/AppTester.d.ts

@@ -12,6 +12,7 @@ import type { AppDocsEmitter } from './workers/AppDocsEmitter.js';
 import type { AppTestSuiteTestResult } from './workers/AppTestSuiteEmitter.js';
 import { AppTesterCtxInitializer } from './workers/AppTesterCtxInitializer.js';
 import { UCExecutor, type UCExecutorExecOutput, type Input as UCExecutorInput } from './workers/UCExecutor.js';
+import { AppFolderChecker } from './workers/checkers/AppFolderChecker.js';
 import { AppI18nChecker } from './workers/checkers/AppI18nChecker.js';
 import { AppIndexChecker } from './workers/checkers/AppIndexChecker.js';
 import { AppManifestChecker } from './workers/checkers/AppManifestChecker.js';
@@ -31,6 +32,7 @@ export interface AppTesterUCTestData<I extends UCInput | undefined = undefined,
 }
 export declare class AppTester {
     private appDocsEmitter;
+    private appFolderChecker;
     private appI18nChecker;
     private appIndexChecker;
     private appManifestChecker;
@@ -51,7 +53,8 @@ export declare class AppTester {
     private testResults;
     private testSummary;
     private ucDefSourcesCheckerOutput;
-    constructor(appDocsEmitter: AppDocsEmitter, appI18nChecker: AppI18nChecker, appIndexChecker: AppIndexChecker, appManifestChecker: AppManifestChecker, appTesterCtxInitializer: AppTesterCtxInitializer, serverManager: ServerManager, simpleHTMLAppTestReportEmitter: SimpleHTMLAppTestReportEmitter, ucBuilder: UCBuilder, ucDefChecker: UCDefChecker, ucDefSourcesChecker: UCDefSourcesChecker, ucExecutor: UCExecutor);
+    constructor(appDocsEmitter: AppDocsEmitter, appFolderChecker: AppFolderChecker, appI18nChecker: AppI18nChecker, appIndexChecker: AppIndexChecker, appManifestChecker: AppManifestChecker, appTesterCtxInitializer: AppTesterCtxInitializer, serverManager: ServerManager, simpleHTMLAppTestReportEmitter: SimpleHTMLAppTestReportEmitter, ucBuilder: UCBuilder, ucDefChecker: UCDefChecker, ucDefSourcesChecker: UCDefSourcesChecker, ucExecutor: UCExecutor);
+    checkAppFolder(): Promise<void>;
     checkAppI18n(): Promise<void>;
     checkAppIndex(): Promise<void>;
     checkAppManifest(): Promise<void>;

package/dist/esm/testing/AppTester.js

@@ -23,6 +23,7 @@ import { allWithExamples, defaultUCInputFillers, } from './uc-input.js';
 import { awaitForSrcImport } from './utils.js';
 import { AppTesterCtxInitializer } from './workers/AppTesterCtxInitializer.js';
 import { UCExecutor, } from './workers/UCExecutor.js';
+import { AppFolderChecker } from './workers/checkers/AppFolderChecker.js';
 import { AppI18nChecker } from './workers/checkers/AppI18nChecker.js';
 import { AppIndexChecker } from './workers/checkers/AppIndexChecker.js';
 import { AppManifestChecker } from './workers/checkers/AppManifestChecker.js';
@@ -30,6 +31,7 @@ import { UCDefChecker } from './workers/checkers/UCDefChecker.js';
 import { UCDefSourcesChecker, } from './workers/checkers/UCDefSourcesChecker.js';
 let AppTester = class AppTester {
     appDocsEmitter;
+    appFolderChecker;
     appI18nChecker;
     appIndexChecker;
     appManifestChecker;
@@ -51,8 +53,9 @@ let AppTester = class AppTester {
     testResults;
     testSummary;
     ucDefSourcesCheckerOutput;
-    constructor(appDocsEmitter, appI18nChecker, appIndexChecker, appManifestChecker, appTesterCtxInitializer, serverManager, simpleHTMLAppTestReportEmitter, ucBuilder, ucDefChecker, ucDefSourcesChecker, ucExecutor) {
+    constructor(appDocsEmitter, appFolderChecker, appI18nChecker, appIndexChecker, appManifestChecker, appTesterCtxInitializer, serverManager, simpleHTMLAppTestReportEmitter, ucBuilder, ucDefChecker, ucDefSourcesChecker, ucExecutor) {
         this.appDocsEmitter = appDocsEmitter;
+        this.appFolderChecker = appFolderChecker;
         this.appI18nChecker = appI18nChecker;
         this.appIndexChecker = appIndexChecker;
         this.appManifestChecker = appManifestChecker;
@@ -72,6 +75,14 @@ let AppTester = class AppTester {
             },
         };
     }
+    async checkAppFolder() {
+        const { errors } = await this.appFolderChecker.exec({
+            appPath: this.ctx.appPath,
+        });
+        if (errors.length > 0) {
+            throw new Error(errors[0]);
+        }
+    }
     async checkAppI18n() {
         const { errors } = await this.appI18nChecker.exec({
             appManifest: this.ctx.appManifest,
@@ -337,17 +348,19 @@ let AppTester = class AppTester {
 AppTester = __decorate([
     injectable(),
     __param(0, inject('AppDocsEmitter')),
-    __param(1, inject(AppI18nChecker)),
-    __param(2, inject(AppIndexChecker)),
-    __param(3, inject(AppManifestChecker)),
-    __param(4, inject(AppTesterCtxInitializer)),
-    __param(5, inject('ServerManager')),
-    __param(6, inject(SimpleHTMLAppTestReportEmitter)),
-    __param(7, inject(UCBuilder)),
-    __param(8, inject(UCDefChecker)),
-    __param(9, inject(UCDefSourcesChecker)),
-    __param(10, inject(UCExecutor)),
-    __metadata("design:paramtypes", [Object, AppI18nChecker,
+    __param(1, inject(AppFolderChecker)),
+    __param(2, inject(AppI18nChecker)),
+    __param(3, inject(AppIndexChecker)),
+    __param(4, inject(AppManifestChecker)),
+    __param(5, inject(AppTesterCtxInitializer)),
+    __param(6, inject('ServerManager')),
+    __param(7, inject(SimpleHTMLAppTestReportEmitter)),
+    __param(8, inject(UCBuilder)),
+    __param(9, inject(UCDefChecker)),
+    __param(10, inject(UCDefSourcesChecker)),
+    __param(11, inject(UCExecutor)),
+    __metadata("design:paramtypes", [Object, AppFolderChecker,
+        AppI18nChecker,
         AppIndexChecker,
         AppManifestChecker,
         AppTesterCtxInitializer, Object, SimpleHTMLAppTestReportEmitter,

package/dist/esm/testing/impl/VitestAppTestSuiteEmitter.js

@@ -92,6 +92,10 @@ test('Sources should be valid', async () => {
     await runner.checkUCDSources();
 });
 
+test('Folder should be valid', async () => {
+    await runner.checkAppFolder();
+});
+
 test('${APP_MANIFEST_NAME} should be valid', async () => {
     await runner.checkAppManifest();
 });
@@ -215,7 +219,7 @@ describe.runIf(ucdRefs.length > 0)('Use Cases', () => {
             for (const k of Object.keys(inputFields)) {
                 inputLike[k] = anything();
             }
-            const cmdArbs = record(inputLike, { withDeletedKeys: true }).map(
+            const cmdArbs = record(inputLike, { requiredKeys: [] }).map(
                 (r) => new MyCommand(r),
             );
 

package/dist/esm/testing/workers/checkers/AppFolderChecker.d.ts

@@ -0,0 +1,17 @@
+import type { ErrorMessage } from '../../../dt/index.js';
+import type { FSManager, Worker } from '../../../std/index.js';
+import type { AppTesterCtx } from '../../ctx.js';
+interface Input {
+    appPath: AppTesterCtx['appPath'];
+}
+interface Output {
+    errors: ErrorMessage[];
+}
+export declare class AppFolderChecker implements Worker<Input, Promise<Output>> {
+    private fsManager;
+    private output;
+    constructor(fsManager: FSManager);
+    exec({ appPath }: Input): Promise<Output>;
+    private makeSureSrcItemsAreAllowed;
+}
+export {};

package/dist/esm/testing/workers/checkers/AppFolderChecker.js

@@ -0,0 +1,51 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { inject, injectable } from 'inversify';
+import { APP_I18N_FILE_NAME, APP_INSTALLER_FILE_NAME, APP_MANIFEST_FILE_NAME, APP_SETTINGS_FILE_NAME, APP_SRC_DIR_NAME, APP_SRC_LIB_DIR_NAME, APP_SRC_UCDS_DIR_NAME, } from '../../../convention.js';
+const ALLOWED_SRC_ITEMS = [
+    APP_SRC_LIB_DIR_NAME,
+    APP_SRC_UCDS_DIR_NAME,
+    APP_I18N_FILE_NAME,
+    APP_INSTALLER_FILE_NAME,
+    APP_MANIFEST_FILE_NAME,
+    APP_SETTINGS_FILE_NAME,
+];
+const ERR_UNALLOWED_SRC_ITEM = (item) => `The app ${APP_SRC_DIR_NAME} folder should contain only the following items : ${ALLOWED_SRC_ITEMS.join(', ')} but found ${item}. Remove it or move it to 'lib'`;
+let AppFolderChecker = class AppFolderChecker {
+    fsManager;
+    output;
+    constructor(fsManager) {
+        this.fsManager = fsManager;
+        this.output = { errors: [] };
+    }
+    async exec({ appPath }) {
+        const srcPath = this.fsManager.path(appPath, APP_SRC_DIR_NAME);
+        const contents = await this.fsManager.ls(srcPath);
+        const items = contents.map((i) => i.path);
+        this.makeSureSrcItemsAreAllowed(items);
+        return this.output;
+    }
+    makeSureSrcItemsAreAllowed(items) {
+        for (const item of items) {
+            if (!ALLOWED_SRC_ITEMS.includes(item)) {
+                this.output.errors.push(ERR_UNALLOWED_SRC_ITEM(item));
+            }
+        }
+    }
+};
+AppFolderChecker = __decorate([
+    injectable(),
+    __param(0, inject('FSManager')),
+    __metadata("design:paramtypes", [Object])
+], AppFolderChecker);
+export { AppFolderChecker };

package/dist/esm/utils/bundling/vite/StripUCDLifecycleServerPlugin.d.ts

@@ -0,0 +1,2 @@
+import type { PluginOption } from 'vite';
+export declare const StripUCDLifecycleServerPlugin: PluginOption;

package/dist/esm/utils/bundling/vite/StripUCDLifecycleServerPlugin.js

@@ -0,0 +1,18 @@
+import { UC_DEF_FILE_NAME_SUFFIX } from '../../../convention.js';
+import { stripUCDLifecycleServer } from '../../../uc/index.js';
+export const StripUCDLifecycleServerPlugin = {
+    // Why enforce ?
+    // Otherwise Rollup parses the file and strips trailing commas.
+    // We need them to strip correctly (although the implementation will be made more robust).
+    enforce: 'pre',
+    name: 'strip-ucd-lifecycle-server',
+    transform: (src, id) => {
+        if (id.match(new RegExp(`${UC_DEF_FILE_NAME_SUFFIX}$`)) === null) {
+            return;
+        }
+        const code = stripUCDLifecycleServer(src);
+        return {
+            code,
+        };
+    },
+};

package/dist/esm/utils/ioc/bindServer.js

@@ -1,6 +1,6 @@
-import { JoseJWTManager } from '../../index.std-jwt-manager-jose.js';
 import { FakeEmailManager } from '../../std/impl/FakeEmailManager.js';
 import { FakeJobManager } from '../../std/impl/FakeJobManager.js';
+import { JoseJWTManager } from '../../std/impl/JoseJWTManager.js';
 export function bindServer(container) {
     // std
     container.bind('EmailManager').to(FakeEmailManager);

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "libmodulor",
     "description": "An opinionated TypeScript library to create business oriented applications",
-    "version": "0.7.0",
+    "version": "0.9.0",
     "license": "LGPL-3.0",
     "author": "Chafik H'nini <chafik.hnini@gmail.com>",
     "homepage": "https://github.com/c100k/libmodulor#readme",
@@ -29,6 +29,9 @@
         "./locales/fr": {
             "import": "./dist/esm/i18n/locales/fr.js"
         },
+        "./node-express": {
+            "import": "./dist/esm/index.node-express.js"
+        },
         "./node-mcp": {
             "import": "./dist/esm/index.node-mcp.js"
         },
@@ -73,27 +76,27 @@
     },
     "peerDependencies": {
         "@hono/node-server": "^1.13.8",
-        "@modelcontextprotocol/sdk": "^1.6.1",
+        "@modelcontextprotocol/sdk": "^1.7.0",
         "@stricli/core": "^1.1.1",
         "buffer": "^6.0.3",
         "cookie-parser": "^1.4.7",
         "express": "^4.21.2",
         "express-fileupload": "^1.5.1",
-        "fast-check": "^3.23.2",
+        "fast-check": "^4.0.0",
         "helmet": "^8.0.0",
-        "hono": "^4.7.2",
+        "hono": "^4.7.4",
         "inversify": "^6.2.2",
-        "jose": "^6.0.8",
+        "jose": "^6.0.10",
         "knex": "^3.1.0",
-        "pg": "^8.13.3",
+        "pg": "^8.14.0",
         "react": "^19.0.0",
         "react-dom": "^19.0.0",
         "react-native": "^0.78.0",
         "reflect-metadata": "^0.2.2",
         "sqlite3": "^5.1.7",
         "typescript": "^5.8.2",
-        "vite": "^6.2.0",
-        "vitest": "^3.0.7"
+        "vite": "^6.2.2",
+        "vitest": "^3.0.8"
     },
     "peerDependenciesMeta": {
         "@hono/node-server": {
@@ -105,6 +108,24 @@
         "@stricli/core": {
             "optional": true
         },
+        "buffer": {
+            "optional": true
+        },
+        "cookie-parser": {
+            "optional": true
+        },
+        "express": {
+            "optional": true
+        },
+        "express-fileupload": {
+            "optional": true
+        },
+        "fast-check": {
+            "optional": true
+        },
+        "helmet": {
+            "optional": true
+        },
         "hono": {
             "optional": true
         },
@@ -131,6 +152,9 @@
         },
         "vite": {
             "optional": true
+        },
+        "vitest": {
+            "optional": true
         }
     },
     "sideEffects": false