libmodulor 0.24.0 → 0.26.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # CHANGELOG
 
+## v0.26.0 (2026-01-01)
+
+**Highlights**
+
+Added new CLI helper commands to create each element of the `libmodulor` 4-layer architecture faster : `CreateApp`, `CreateUC`, `CreateProduct`, `CreateTarget`.
+Check them out with `npx libmodulor --help` (or `pnpm libmodulor --help` within a project with `libmodulor` installed).
+
+Simplified settings management : moved to more and better defaults so you don't have to provide any settings when creating new product targets (see [Create a target](https://libmodulor.c100k.eu/docs/guides/create-target)).
+
+Simplified testing : replaced `SimpleAppTesterConfigurator` by `NodeAppTesterConfigurator` including the necessary bindings to have tests working out of the box (see [Test an app](https://libmodulor.c100k.eu/docs/guides/test-app)). The `GenerateAppsTests` CLI command now generates a default `Configurator.ts` if it does not exist yet.
+
+Moved all the targets of a product into a dedicated `targets` dir so they are not mixed with other types of directories you might have in a product (e.g. specific utilities, implementations, etc.).
+
+See all the changes here : https://github.com/c100k/libmodulor/compare/v0.25.0...master
+
+## v0.25.0 (2025-12-21)
+
+**Highlights**
+
+- Added use case summary in the auto-generated app docs : In addition to the existing mermaid diagram, there is now a summary of the lifecyle, input and output in a dedicated table
+    - Example : https://github.com/c100k/libmodulor/tree/42fd11307cdd9f8cdec19b4de75d4959bc9f9a9e/examples/apps/Spotify#createalbum
+- Improved the `File` data type
+    - Changed the property `path` to `uri` to conform to the `FormData` spec (this is a breaking change)
+    - Simplified the declaration by inlining the accepted types via `accept` instead of `type.allowed` (this is also a breaking change)
+    - Added `maxSizeInBytes` and `minSizeInBytes` for size validation
+- Added `getConstraintsForHuman` to format constraints for the end user in the targets. For instance :
+    - For `FreeTextShort`, it displays `Max length: 150` 🇬🇧 when present
+    - For `File`, it displays `Max size: 8MB - Accepted types: application/png, application/jpg` 🇬🇧 when present
+    - Applied to the `react-native-pure` and `react-native-web` targets (see `UCFormFieldHelp.tsx`)
+
+See all the changes here : https://github.com/c100k/libmodulor/compare/v0.24.0...master
+
 ## v0.24.0 (2025-12-07)
 
 **Highlights**

package/README.md

@@ -5,163 +5,44 @@
 
 A TypeScript library to create platform-agnostic applications.
 
-## 🚀 Getting Started
-
-If you're discovering `libmodulor`, we recommend reading the [📖 Documentation](https://libmodulor.c100k.eu/docs) first.
-You'll find everything you need to get started : Concepts, Examples and Guides.
-
-When you're ready, [🚀 Create a project](https://libmodulor.c100k.eu/docs/guides/create-project) and build the awesome idea you have in mind.
-
-In the meantime, here is how to declare the four layers of `libmodulor`.
-
-_These snippets are extracted from the [`Basic`](https://libmodulor.c100k.eu/docs/examples/Basic) example (check out the full example to get the full picture)._
-
-### App
-
-```ts
-const appManifest = {
-    languageCodes: ['en', 'fr'],
-    name: 'Event',
-    ucReg: {
-        Register: {
-            action: 'Create',
-            icon: 'user',
-            name: 'Register',
-        },
-    },
-} satisfies AppManifest;
-
-const appI18n: AppI18n = {
-    en: {
-        ucif_email_label: 'Your email address',
-        ucif_firstname_label: 'Your firstname',
-        ucif_lastname_label: 'Your lastname',
-        ucof_id_label: 'Your registration #',
-        ucof_ticketNumber_label: 'Your ticket #',
-    },
-    fr: {
-        ucif_email_label: 'Votre adresse email',
-        ucif_firstname_label: 'Votre prénom',
-        ucif_lastname_label: 'Votre nom',
-        ucof_id_label: "Votre # d'inscription",
-        ucof_ticketNumber_label: 'Votre # de ticket',
-    },
-};
-```
+## Links
 
-### Use Case
-
-```ts
-interface RegisterInput extends UCInput {
-    email: UCInputFieldValue<Email>;
-    firstname: UCInputFieldValue<PersonFirstname>;
-    lastname: UCInputFieldValue<PersonLastname>;
-}
-
-interface RegisterOPI0 extends AggregateOPI0 {
-    amount: Amount;
-    ticketNumber: TicketNumber;
-}
-
-@injectable()
-class RegisterClientMain implements UCMain<RegisterInput, RegisterOPI0> {
-    constructor(@inject('UCManager') private ucManager: UCManager) {}
-
-    public async exec({
-        uc,
-    }: UCMainInput<RegisterInput, RegisterOPI0>): Promise<
-        UCOutput<RegisterOPI0>
-    > {
-        const { aggregateId } = await this.ucManager.persist(uc);
-
-        const amount: Amount = 99.99; // Should come from some catalog in a real application
-        const ticketNumber: TicketNumber = 1; // Should come from a safely auto-generated sequence in a real application
-
-        return new UCOutputBuilder<RegisterOPI0>()
-            .add({
-                amount,
-                id: aggregateId,
-                ticketNumber,
-            })
-            .get();
-    }
-}
-
-const RegisterUCD: UCDef<RegisterInput, RegisterOPI0> = {
-    io: {
-        i: {
-            fields: {
-                email: {
-                    type: new TEmail(),
-                },
-                firstname: {
-                    type: new TPersonFirstname(),
-                },
-                lastname: {
-                    type: new TPersonLastname(),
-                },
-            },
-        },
-        o: {
-            parts: {
-                _0: {
-                    fields: {
-                        amount: {
-                            type: new TAmount('EUR'),
-                        },
-                        ticketNumber: {
-                            type: new TTicketNumber(),
-                        },
-                    },
-                    order: ['ticketNumber', 'amount', 'id'],
-                },
-            },
-        },
-    },
-    lifecycle: {
-        client: {
-            main: RegisterClientMain,
-            policy: EverybodyUCPolicy,
-        },
-    },
-    metadata: {
-        action: 'Create',
-        icon: 'user',
-        name: 'Register',
-    },
-};
-```
+- [Website](https://libmodulor.c100k.eu)
+- [Documentation](https://libmodulor.c100k.eu/docs)
+- [Concepts > Philosophy](https://libmodulor.c100k.eu/docs/concepts/philosophy)
+- [Examples > Playground](https://libmodulor.c100k.eu/docs/examples/Playground)
+- [Guides > Playground](https://libmodulor.c100k.eu/docs/guides/create-project)
 
-### Product
-
-```ts
-const productManifest: ProductManifest = {
-    appReg: [{ name: 'Event' }],
-    name: 'Eventer',
-};
-
-const productI18n: ProductI18n = {
-    en: {
-        ...I18nEN,
-        ...appI18n.en,
-    },
-    fr: {
-        ...I18nFR,
-        ...appI18n.fr,
-    },
-};
-```
+## Getting Started
+
+As described in the [Architecture](https://libmodulor.c100k.eu/docs/concepts/architecture) concept, `libmodulor` follows a 4-layer architecture with `UseCase`, `App`, `Product`, and `Target`.
 
-### Target
+Here is how to easily create all of them, in a brand new project :
 
-```ts
-const container = new Container(CONTAINER_OPTS);
+```sh
+# Create a project
+npx libmodulor CreateProject --projectName my-super-project
+cd my-super-project
 
-bindCommon(container);
-bindNodeCore(container);
-bindProduct(container, productManifest, productI18n);
+# Create an app
+pnpm libmodulor CreateApp --appName Banking
+
+# Create a use case
+pnpm libmodulor CreateUC --appName Banking --ucName CreateAccount
+
+# Create a product
+pnpm libmodulor CreateProduct --productName CustomerPortal
+
+# Create a target
+pnpm libmodulor CreateTarget --productName CustomerPortal --targetName node-express-server
+pnpm libmodulor CreateTarget --productName CustomerPortal --targetName node-hono-server
+pnpm libmodulor CreateTarget --productName CustomerPortal --targetName node-core-cli
+pnpm libmodulor CreateTarget --productName CustomerPortal --targetName node-mcp-server
 ```
 
+For more params, checkout the help section : `pnpm libmodulor --help`.
+
+And for more details on the code, follow the ad-hoc guides in the documentation.
 
 ## 👨‍💻 Contribute
 
@@ -169,4 +50,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.24.0/LICENSE)
+[LGPL-3.0](https://github.com/c100k/libmodulor/blob/v0.26.0/LICENSE)

package/dist/esm/app/workers/AppUCsLoader.d.ts

@@ -6,11 +6,10 @@ import type { AppManifestSourceSafe } from '../manifest.js';
 import { AppManifestLoader } from './AppManifestLoader.js';
 import type { Input as AppSrcFilePathBuilderInput } from './AppSrcFilePathBuilder.js';
 import { UCDefLoader } from './UCDefLoader.js';
-export interface Input {
+export type Input = Pick<AppSrcFilePathBuilderInput, 'appsRootPath'> & {
     app: ProductAppReg;
-    appsRootPath?: AppSrcFilePathBuilderInput['appsRootPath'];
     srcImporter: SrcImporter<AppManifestSourceSafe | UCDefSourceSafe>;
-}
+};
 export type Output = UC<any, any, any>[];
 export declare class AppUCsLoader implements Worker<Input, Promise<Output>> {
     private appManifestLoader;

package/dist/esm/apps/Helper/src/i18n.d.ts

@@ -1,2 +1,39 @@
-import type { AppI18n } from '../../../index.js';
-export declare const I18n: AppI18n;
+export declare const I18n: {
+    en: {
+        err_existing_app: string;
+        err_existing_product: string;
+        err_existing_target: string;
+        err_target_generator_not_available: string;
+        err_unknown_app: string;
+        uc_CreateApp_desc: string;
+        uc_CreateApp_label: string;
+        uc_CreateProduct_desc: string;
+        uc_CreateProduct_label: string;
+        uc_CreateProject_desc: string;
+        uc_CreateProject_label: string;
+        uc_CreateTarget_desc: string;
+        uc_CreateTarget_label: string;
+        uc_CreateUC_desc: string;
+        uc_CreateUC_label: string;
+        uc_DeleteGeneratedAppsTests_desc: string;
+        uc_DeleteGeneratedAppsTests_label: string;
+        uc_GenerateAppsTests_desc: string;
+        uc_GenerateAppsTests_label: string;
+        uc_TestApp_desc: string;
+        uc_TestApp_label: string;
+        ucif_appName_desc: string;
+        ucif_appPath_desc: string;
+        ucif_appsPath_desc: string;
+        ucif_depsMapping_desc: string;
+        ucif_initialCommit_desc: string;
+        ucif_monkeyTestingTimeoutInMs_desc: string;
+        ucif_outPath_desc: string;
+        ucif_pkgManagerBin_desc: string;
+        ucif_productName_desc: string;
+        ucif_projectName_desc: string;
+        ucif_scmBin_desc: string;
+        ucif_serverPortRangeStart_desc: string;
+        ucif_skipCoverage_desc: string;
+        ucif_updateSnapshots_desc: string;
+    };
+};

package/dist/esm/apps/Helper/src/i18n.js

@@ -1,14 +1,27 @@
 export const I18n = {
     en: {
-        err_unknown_app: 'Unknown app : {{appPath}}',
+        err_existing_app: 'App "{{appPath}}" already exists',
+        err_existing_product: 'Product "{{productPath}}" already exists',
+        err_existing_target: 'Target "{{targetPath}}" already exists',
+        err_target_generator_not_available: 'This target has not been implemented yet via the generator. In the meantime, you can create it manually by following the examples.',
+        err_unknown_app: 'App "{{appPath}}" does not exist',
+        uc_CreateApp_desc: 'Create the basics of an app (index, i18n, manifest)',
+        uc_CreateApp_label: 'Create an app',
+        uc_CreateProduct_desc: 'Create the basics of a product (i18n, manifest)',
+        uc_CreateProduct_label: 'Create a product',
         uc_CreateProject_desc: 'Create a project by initializing a git repo, creating basic config files and installing the required dependencies',
         uc_CreateProject_label: 'Create a project',
+        uc_CreateTarget_desc: 'Create a target based on the ones provided by the lib (see https://libmodulor.c100k.eu/docs/references/targets)',
+        uc_CreateTarget_label: 'Create a target',
+        uc_CreateUC_desc: 'Create a basic use case',
+        uc_CreateUC_label: 'Create a use case',
         uc_DeleteGeneratedAppsTests_desc: 'Delete the automated test suite generated for each app',
         uc_DeleteGeneratedAppsTests_label: 'Delete generated apps tests',
         uc_GenerateAppsTests_desc: 'Generate an automated test suite for each app',
         uc_GenerateAppsTests_label: 'Generate apps tests',
         uc_TestApp_desc: 'Test an app and generate coverage report',
         uc_TestApp_label: 'Test app',
+        ucif_appName_desc: 'Name of the app conforming to the spec (i.e. PascalCase : A-Z, 0-9)',
         ucif_appPath_desc: 'The path of the app',
         ucif_appsPath_desc: 'The path to the directory containing all the apps',
         ucif_depsMapping_desc: 'The mapping of dependencies in case some of them need a specific pattern (e.g. one directory above the default)',
@@ -16,6 +29,7 @@ export const I18n = {
         ucif_monkeyTestingTimeoutInMs_desc: 'These tests can take longer than the usual default of 5000ms because they try lots of possibilities',
         ucif_outPath_desc: 'Path to a directory where to create the project. Do not include the project name in it. It is created recursively if missing.',
         ucif_pkgManagerBin_desc: "The package manager to use to install the deps and run the dev commands (must conform to npm's API)",
+        ucif_productName_desc: 'Name of the product conforming to the spec (i.e. PascalCase : A-Z, 0-9)',
         ucif_projectName_desc: "Name of the project conforming to the package.json's spec (i.e. a-z, 0-9, -)",
         ucif_scmBin_desc: "The source control manager to use to init and commit (must conform to git's API)",
         ucif_serverPortRangeStart_desc: 'The port number to start with when generating the server to test (incremented by 1) for each app',

package/dist/esm/apps/Helper/src/lib/SrcFilesGenerator.d.ts

@@ -0,0 +1,13 @@
+import type { DirPath, FilePath } from '../../../../dt/index.js';
+import type { FSManager, Worker } from '../../../../std/index.js';
+export type Files = Map<FilePath[], string>;
+interface Input {
+    files: Files;
+    rootPath: DirPath;
+}
+export declare class SrcFilesGenerator implements Worker<Input, Promise<void>> {
+    private fsManager;
+    constructor(fsManager: FSManager);
+    exec({ files, rootPath }: Input): Promise<void>;
+}
+export {};

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

@@ -0,0 +1,37 @@
+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';
+let SrcFilesGenerator = class SrcFilesGenerator {
+    fsManager;
+    constructor(fsManager) {
+        this.fsManager = fsManager;
+    }
+    async exec({ files, rootPath }) {
+        for await (const [filePath, content] of files) {
+            const fileName = filePath[filePath.length - 1];
+            if (!fileName) {
+                throw new Error(`Incorrect file path : ${filePath}`);
+            }
+            const rest = filePath.slice(0, -1);
+            const path = this.fsManager.path(rootPath, ...rest);
+            await this.fsManager.mkdir(path, { recursive: true });
+            await this.fsManager.touch(this.fsManager.path(rootPath, ...filePath), content);
+        }
+    }
+};
+SrcFilesGenerator = __decorate([
+    injectable(),
+    __param(0, inject('FSManager')),
+    __metadata("design:paramtypes", [Object])
+], SrcFilesGenerator);
+export { SrcFilesGenerator };

package/dist/esm/apps/Helper/src/lib/consts.d.ts

@@ -0,0 +1,2 @@
+export declare const LIB_NAME = "libmodulor";
+export declare const GIT_KEEP_FILE_NAME = ".gitkeep";

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

@@ -0,0 +1,2 @@
+export const LIB_NAME = 'libmodulor';
+export const GIT_KEEP_FILE_NAME = '.gitkeep';

package/dist/esm/apps/Helper/src/lib/funcs.d.ts

@@ -0,0 +1,4 @@
+import type { FileName } from '../../../../dt/index.js';
+import type { Creatable } from './types.js';
+export declare function fileImportName(name: FileName): FileName;
+export declare function successMessage(item: Creatable): string;

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

@@ -0,0 +1,9 @@
+export function fileImportName(name) {
+    if (name.endsWith('.ts')) {
+        return name.replaceAll('.ts', '.js');
+    }
+    return `${name}.js`;
+}
+export function successMessage(item) {
+    return `${item} created successfully !`;
+}

package/dist/esm/apps/Helper/src/lib/io.d.ts

@@ -0,0 +1,10 @@
+import { type DirPath } from '../../../../dt/index.js';
+import type { UCInput, UCInputDef, UCInputFieldValue } from '../../../../uc/index.js';
+export interface AppInput extends UCInput {
+    appsPath: UCInputFieldValue<DirPath>;
+}
+export declare const AppInputFieldsDef: UCInputDef<AppInput>['fields'];
+export interface ProductInput extends UCInput {
+    productsPath: UCInputFieldValue<DirPath>;
+}
+export declare const ProductInputFieldsDef: UCInputDef<ProductInput>['fields'];

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

@@ -0,0 +1,22 @@
+import { APPS_ROOT_PATH, PRODUCTS_ROOT_PATH } from '../../../../convention.js';
+import { TDirPath } from '../../../../dt/index.js';
+export const AppInputFieldsDef = {
+    appsPath: {
+        cardinality: {
+            min: 0,
+        },
+        type: new TDirPath()
+            .setDefaultValue(APPS_ROOT_PATH.join('/'))
+            .setExamples([APPS_ROOT_PATH.join('/')]),
+    },
+};
+export const ProductInputFieldsDef = {
+    productsPath: {
+        cardinality: {
+            min: 0,
+        },
+        type: new TDirPath()
+            .setDefaultValue(PRODUCTS_ROOT_PATH.join('/'))
+            .setExamples([PRODUCTS_ROOT_PATH.join('/')]),
+    },
+};

package/dist/esm/apps/Helper/src/lib/layers/app.d.ts

@@ -0,0 +1,3 @@
+import type { AppName } from '../../../../../app/index.js';
+import type { Files } from '../types.js';
+export declare function files(name: AppName): Files;

package/dist/esm/apps/Helper/src/lib/layers/app.js

@@ -0,0 +1,30 @@
+import { APP_I18N_FILE_NAME, APP_I18N_NAME, APP_INDEX_FILE_NAME, APP_MANIFEST_FILE_NAME, APP_MANIFEST_NAME, APP_SRC_DIR_NAME, } from '../../../../../convention.js';
+import { I18N_DEFAULT_LANG } from '../../../../../i18n/index.js';
+import { LIB_NAME } from '../consts.js';
+import { fileImportName } from '../funcs.js';
+const INDEX_TS = `// Expose only what's necessary
+
+export { ${APP_I18N_NAME} } from './${APP_SRC_DIR_NAME}/${fileImportName(APP_I18N_FILE_NAME)}';
+export { ${APP_MANIFEST_NAME} } from './${APP_SRC_DIR_NAME}/${fileImportName(APP_MANIFEST_FILE_NAME)}';
+`;
+const I18N_TS = `import type { AppI18n } from '${LIB_NAME}';
+
+export const ${APP_I18N_NAME} = {
+    ${I18N_DEFAULT_LANG}: {},
+} satisfies AppI18n;
+`;
+const MANIFEST_TS = (name) => `import type { AppManifest } from '${LIB_NAME}';
+
+export const ${APP_MANIFEST_NAME} = {
+    languageCodes: ['${I18N_DEFAULT_LANG}'],
+    name: '${name}',
+    ucReg: {},
+} satisfies AppManifest;
+`;
+export function files(name) {
+    return new Map([
+        [['.', APP_INDEX_FILE_NAME], INDEX_TS],
+        [[APP_SRC_DIR_NAME, APP_I18N_FILE_NAME], I18N_TS],
+        [[APP_SRC_DIR_NAME, APP_MANIFEST_FILE_NAME], MANIFEST_TS(name)],
+    ]);
+}

package/dist/esm/apps/Helper/src/lib/layers/product.d.ts

@@ -0,0 +1,3 @@
+import type { ProductName } from '../../../../../product/index.js';
+import type { Files } from '../types.js';
+export declare function files(name: ProductName): Files;

package/dist/esm/apps/Helper/src/lib/layers/product.js

@@ -0,0 +1,27 @@
+import { PRODUCT_I18N_FILE_NAME, PRODUCT_I18N_NAME, PRODUCT_MANIFEST_FILE_NAME, PRODUCT_MANIFEST_NAME, } from '../../../../../convention.js';
+import { I18N_DEFAULT_LANG } from '../../../../../i18n/index.js';
+import { LIB_NAME } from '../consts.js';
+const I18N_TS = `import type { ProductI18n } from '${LIB_NAME}';
+import { I18n${I18N_DEFAULT_LANG.toLocaleUpperCase()} } from 'libmodulor/locales/${I18N_DEFAULT_LANG}';
+
+export const ${PRODUCT_I18N_NAME} = {
+    ${I18N_DEFAULT_LANG}: {
+        ...I18n${I18N_DEFAULT_LANG.toLocaleUpperCase()},
+        p_desc: '',
+        p_slogan: '',
+    },
+} satisfies ProductI18n;
+`;
+const MANIFEST_TS = (name) => `import type { ProductManifest } from '${LIB_NAME}';
+
+export const ${PRODUCT_MANIFEST_NAME} = {
+    appReg: [],
+    name: '${name}',
+} satisfies ProductManifest;
+`;
+export function files(name) {
+    return new Map([
+        [['.', PRODUCT_I18N_FILE_NAME], I18N_TS],
+        [['.', PRODUCT_MANIFEST_FILE_NAME], MANIFEST_TS(name)],
+    ]);
+}

package/dist/esm/apps/Helper/src/lib/layers/project.d.ts

@@ -0,0 +1,4 @@
+import type { Slug } from '../../../../../dt/index.js';
+import type { Files } from '../types.js';
+export declare const PACKAGE_JSON: (name: Slug) => string;
+export declare function files(name: Slug): Files;