libmodulor 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # CHANGELOG
 
+## v0.7.0 (2025-03-07)
+
+**Added**
+
+- Make `npx libmodulor CreateProject` more generic : you can now customize the `initialCommit` (default is `chore: initial commit`), the `pkgManagerBin` (default is `yarn`, works with `npm`, `pnpm`, `bun`, etc.), the `scmBin` (default is `git`)
+
+**Fixed**
+
+- Derandomize UC input before snapshotting in tests : after the upgrade to TS 5.8, snapshotting a UC including a File as input would break as a new `state` property has appeared with a dynamic `lastModified` property
+
+**Misc**
+
+- Move the documentation with concepts, examples, guides and references to https://libmodulor.c100k.eu
+
 ## v0.6.1 (2025-02-28)
 
 **Fixed**

package/README.md

@@ -5,39 +5,17 @@
 
 An opinionated TypeScript library to create business oriented applications.
 
-Applications created with `libmodulor` have **6 main properties** :
-
-- Strictly typed with explicit business data types
-- Fully typed e2e without code generation
-- Auto documented
-- Auto tested
-- Multi platforms/runtimes
-- Runnable anywhere
-
 > [!WARNING]
 > The project is still in active development. Although already used in pilot projects, it's not suitable for all production scenarios yet.
 > Being developed by only one person, it may keep going for years or stop at any time.
 > In the meantime, it's still a "research project" that needs improvement. Thus, it will be subject to BREAKING CHANGES as long as the version is not `1.0.0`.
-> All that said, the end goal is really to have a **production-grade library** to help everyone build **quality projects faster**. If you want to help in any way or have questions, feel free to contact me (cf. `author` in `package.json`).
-
-> [!NOTE]
-> At the beginning, the whole documentation will be on GitHub, starting from this file, to make it easier to have the big picture, maintain and <kbd>cmd</kbd> + <kbd>F</kbd>. At some point, I'll consider having a beautiful documentation website like all the cool kids.
-
----
+> All that said, the end goal is really to have a **production-grade library** to help everyone build **quality projects faster**.
 
 ## 🚀 Getting Started
 
-If you're discovering `libmodulor`, we recommend reading the [📖 Introduction](https://github.com/c100k/libmodulor/blob/v0.6.1/docs/Introduction.md) first. It will give you an overview of what `libmodulor` is and how it works.
-
-If you want to learn by doing, you can follow the [🚀 Tutorial](https://github.com/c100k/libmodulor/blob/v0.6.1/docs/Tutorial.md). It contains multiple steps showing you the basics of `libmodulor`. We'll build a small Trading app that will allow us to buy an asset from `curl`, a SPA, a CLI, Claude Desktop, an Android mobile app and an iOS mobile app !
-
-If you're felling adventurous, create a project and start building your own application, with your own apps, use cases, products, targets :
-
-```sh
-npx libmodulor CreateProject --outPath ~/Downloads --projectName libmodulor-projx
-```
+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.
 
-Finally, for more advanced uses, check out the [📜 Guides](https://github.com/c100k/libmodulor/blob/v0.6.1/docs/Guides.md).
+When you're ready, [🚀 Create a project](https://libmodulor.c100k.eu/docs/guides/create-project) and build the awesome idea you have in mind.
 
 ## 👨‍💻 Contribute
 
@@ -45,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.6.1/LICENSE)
+[LGPL-3.0](https://github.com/c100k/libmodulor/blob/v0.7.0/LICENSE)

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

@@ -11,10 +11,13 @@ export const I18n = {
         uc_TestApp_label: 'Test app',
         ucif_appPath_desc: 'The path of the app',
         ucif_appsPath_desc: 'The path to the directory containing all the apps',
-        ucif_projectName_desc: "Name of the project conforming to the package.json's spec (i.e. a-z, 0-9, -)",
-        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_monkeyTestingTimeoutInMs_desc: 'These tests can take longer than the usual default of 5000ms because they try lots of possibilities',
         ucif_depsMapping_desc: 'The mapping of dependencies in case some of them need a specific pattern (e.g. one directory above the default)',
+        ucif_initialCommit_desc: 'The message of the initial commit',
+        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_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',
         ucif_skipCoverage_desc: 'Whether to skip coverage or not',
         ucif_updateSnapshots_desc: "Whether to update the snapshots or not. Typically, update them if the tests fail because the snapshots don't match, the reason being that you changed the implementation",

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

@@ -1,2 +1,3 @@
 import type { FileName, Slug } from '../../../../dt/index.js';
+export declare const PACKAGE_JSON: (name: Slug) => string;
 export declare function projectFiles(name: Slug): Map<FileName, string>;

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

@@ -26,7 +26,7 @@ const BIOME_JSON = `{
     }
 }
 `;
-const PACKAGE_JSON = (name) => `{
+export const PACKAGE_JSON = (name) => `{
     "name": "${name}",
     "version": "0.1.0",
     "type": "module",
@@ -42,7 +42,7 @@ const PACKAGE_JSON = (name) => `{
     },
     "devDependencies": {
         "@biomejs/biome": "^1.9.4",
-        "@types/node": "^22.13.5",
+        "@types/node": "^22.13.8",
         "@vitest/coverage-v8": "^3.0.7",
         "buffer": "^6.0.3",
         "cookie-parser": "^1.4.7",
@@ -51,7 +51,7 @@ const PACKAGE_JSON = (name) => `{
         "fast-check": "^3.23.2",
         "helmet": "^8.0.0",
         "jose": "^6.0.8",
-        "typescript": "^5.7.3",
+        "typescript": "^5.8.2",
         "vite": "^6.2.0",
         "vitest": "^3.0.7"
     }

package/dist/esm/apps/Helper/src/ucds/CreateProjectUCD.d.ts

@@ -1,9 +1,12 @@
-import { type DirPath, type Slug } from '../../../../dt/index.js';
+import { type DirPath, type FileName, type FreeTextShort, type Slug } from '../../../../dt/index.js';
 import type { FSManager, Logger, ShellCommandExecutor } from '../../../../std/index.js';
 import { type UCDef, type UCInput, type UCInputFieldValue, type UCMain, type UCMainInput } from '../../../../uc/index.js';
 export interface CreateProjectInput extends UCInput {
+    initialCommit: UCInputFieldValue<FreeTextShort>;
     outPath: UCInputFieldValue<DirPath>;
+    pkgManagerBin: UCInputFieldValue<FileName>;
     projectName: UCInputFieldValue<Slug>;
+    scmBin: UCInputFieldValue<FileName>;
 }
 export declare class CreateProjectClientMain implements UCMain<CreateProjectInput> {
     private fsManager;
@@ -11,5 +14,13 @@ export declare class CreateProjectClientMain implements UCMain<CreateProjectInpu
     private shellCommandExecutor;
     constructor(fsManager: FSManager, logger: Logger, shellCommandExecutor: ShellCommandExecutor);
     exec({ uc }: UCMainInput<CreateProjectInput>): Promise<void>;
+    private assertBinPresence;
+    private commit;
+    private createConfigFiles;
+    private createDirs;
+    private createRootDir;
+    private initRepository;
+    private installDeps;
+    private runDevCmds;
 }
 export declare const CreateProjectUCD: UCDef<CreateProjectInput>;

package/dist/esm/apps/Helper/src/ucds/CreateProjectUCD.js

@@ -12,7 +12,8 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { inject, injectable } from 'inversify';
 import { APPS_ROOT_PATH, PRODUCTS_ROOT_PATH } from '../../../../convention.js';
-import { TDirPath, TSlug, } from '../../../../dt/index.js';
+import { TDirPath, TFileName, TFreeTextShort, TSlug, } from '../../../../dt/index.js';
+import { IllegalArgumentError } from '../../../../error/index.js';
 import { EverybodyUCPolicy, } from '../../../../uc/index.js';
 import { projectFiles } from '../lib/project.js';
 import { Manifest } from '../manifest.js';
@@ -26,55 +27,95 @@ let CreateProjectClientMain = class CreateProjectClientMain {
         this.shellCommandExecutor = shellCommandExecutor;
     }
     async exec({ uc }) {
+        const initialCommit = uc.reqVal0('initialCommit');
         const outPath = uc.reqVal0('outPath');
+        const pkgManagerBin = uc.reqVal0('pkgManagerBin');
         const projectName = uc.reqVal0('projectName');
+        const scmBin = uc.reqVal0('scmBin');
+        await this.assertBinPresence(pkgManagerBin);
+        await this.assertBinPresence(scmBin);
         const cwd = this.fsManager.path(outPath, projectName);
-        this.logger.info('Creating root dir : %s', cwd);
-        await this.fsManager.mkdir(cwd, { recursive: true });
-        this.logger.info('Initializing git repository');
-        await this.shellCommandExecutor.exec({
-            bin: 'git',
-            opts: { args: ['init'], cwd },
-        });
-        this.logger.info('Creating config files');
+        // TODO : Rollback the whole thing in case of failure
+        await this.createRootDir(cwd);
+        await this.initRepository(scmBin, cwd);
+        await this.createConfigFiles(projectName, cwd);
+        await this.createDirs(cwd);
+        await this.installDeps(pkgManagerBin, cwd);
+        await this.commit(scmBin, initialCommit, cwd);
+        await this.runDevCmds(pkgManagerBin, cwd);
+        this.logger.info('Done ! Project ready ! ✅ 🚀');
+    }
+    async assertBinPresence(bin) {
+        try {
+            await this.shellCommandExecutor.exec({
+                bin: bin,
+                opts: { args: ['--version'] },
+            });
+        }
+        catch (err) {
+            throw new IllegalArgumentError(`'${bin}' seems missing. Is it installed on your machine ?`);
+        }
+    }
+    async commit(scmBin, initialCommit, cwd) {
+        this.logger.info('Committing');
+        const cmdArgs = [
+            ['branch', '-M', 'master'],
+            ['add', '.'],
+            ['commit', '-am', initialCommit],
+        ];
+        for await (const args of cmdArgs) {
+            await this.shellCommandExecutor.exec({
+                bin: scmBin,
+                opts: { args, cwd },
+            });
+        }
+    }
+    async createConfigFiles(projectName, cwd) {
         const files = projectFiles(projectName);
         for await (const [fileName, content] of files) {
             const path = this.fsManager.path(cwd, fileName);
             await this.fsManager.touch(path, content);
         }
-        const dirs = [APPS_ROOT_PATH, PRODUCTS_ROOT_PATH];
+    }
+    async createDirs(cwd) {
         this.logger.info('Creating apps and products directories');
+        const dirs = [APPS_ROOT_PATH, PRODUCTS_ROOT_PATH];
         for await (const dirPath of dirs) {
             const path = this.fsManager.path(cwd, ...dirPath);
             await this.fsManager.mkdir(path, { recursive: true });
             await this.fsManager.touch(this.fsManager.path(path, '.gitkeep'), '');
         }
-        this.logger.info('Installing dependencies');
+    }
+    async createRootDir(cwd) {
+        this.logger.info('Creating root dir : %s', cwd);
+        await this.fsManager.mkdir(cwd, { recursive: true });
+    }
+    async initRepository(scmBin, cwd) {
+        const cmd = 'init';
+        this.logger.info('Initializing repository : %s %s', scmBin, cmd);
         await this.shellCommandExecutor.exec({
-            bin: 'yarn',
-            opts: { args: ['install'], cwd },
+            bin: scmBin,
+            opts: { args: [cmd], cwd },
         });
-        this.logger.info('Committing');
-        const cmdArgs = [
-            ['branch', '-M', 'master'],
-            ['add', '.'],
-            ['commit', '-am', '"chore: initial commit"'],
-        ];
-        for await (const args of cmdArgs) {
-            await this.shellCommandExecutor.exec({
-                bin: 'git',
-                opts: { args, cwd },
-            });
-        }
-        const devCmds = ['lint', 'test'];
-        for await (const cmd of devCmds) {
-            this.logger.info('Testing dev command : yarn %s', cmd);
+    }
+    async installDeps(pkgManagerBin, cwd) {
+        const cmd = 'install';
+        this.logger.info('Installing dependencies : %s %s', pkgManagerBin, cmd);
+        await this.shellCommandExecutor.exec({
+            bin: pkgManagerBin,
+            opts: { args: [cmd], cwd },
+        });
+    }
+    async runDevCmds(pkgManagerBin, cwd) {
+        const cmd = 'run';
+        const scripts = ['lint', 'test'];
+        for await (const script of scripts) {
+            this.logger.info('Running dev command : %s %s %s', pkgManagerBin, cmd, script);
             await this.shellCommandExecutor.exec({
-                bin: 'yarn',
-                opts: { args: [cmd], cwd },
+                bin: pkgManagerBin,
+                opts: { args: [cmd, script], cwd },
             });
         }
-        this.logger.info('Done ! Project ready ! ✅ 🚀');
     }
 };
 CreateProjectClientMain = __decorate([
@@ -94,6 +135,14 @@ export const CreateProjectUCD = {
     io: {
         i: {
             fields: {
+                initialCommit: {
+                    cardinality: {
+                        min: 0,
+                    },
+                    type: new TFreeTextShort()
+                        .setDefaultValue('chore: initial commit')
+                        .setExamples(['chore: initial commit']),
+                },
                 outPath: {
                     cardinality: {
                         min: 0,
@@ -102,9 +151,25 @@ export const CreateProjectUCD = {
                         .setDefaultValue('./')
                         .setExamples([['~', 'Desktop'].join('/')]),
                 },
+                pkgManagerBin: {
+                    cardinality: {
+                        min: 0,
+                    },
+                    type: new TFileName()
+                        .setDefaultValue('yarn')
+                        .setExamples(['bun', 'npm', 'pnpm', 'yarn']),
+                },
                 projectName: {
                     type: new TSlug(),
                 },
+                scmBin: {
+                    cardinality: {
+                        min: 0,
+                    },
+                    type: new TFileName()
+                        .setDefaultValue('git')
+                        .setExamples(['git']),
+                },
             },
         },
     },

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

@@ -21,7 +21,7 @@ let NodeSpawnShellCommandExecutor = class NodeSpawnShellCommandExecutor {
             proc.stdout.on('data', (chunk) => {
                 stdout += chunk;
             });
-            proc.stdout.on('error', (err) => {
+            proc.on('error', (err) => {
                 reject(err);
             });
             proc.on('close', (code, signal) => {

package/dist/esm/testing/workers/UCExecutor.d.ts

@@ -42,4 +42,6 @@ export declare class UCExecutor implements Worker<Input, Promise<Output>> {
     exec<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined>({ appManifest, auth, authName, inputFiller, inputFillerName, ucd, }: Input<I, OPI0, OPI1>): Promise<Output<I, OPI0, OPI1>>;
     overrideUCManager(ucManager: UCManager): void;
     private execClient;
+    private derandomizeInput;
+    private derandomizeInputFile;
 }

package/dist/esm/testing/workers/UCExecutor.js

@@ -83,6 +83,36 @@ let UCExecutor = class UCExecutor {
         catch (err) {
             out.err = err;
         }
+        finally {
+            this.derandomizeInput(out.io.i);
+        }
+    }
+    derandomizeInput(input) {
+        for (const [k, v] of Object.entries(input)) {
+            if (Array.isArray(v)) {
+                v.forEach((vv, idx) => {
+                    if (vv instanceof File) {
+                        // @ts-ignore
+                        input[k][idx] = this.derandomizeInputFile(vv);
+                    }
+                });
+            }
+            else if (v instanceof File) {
+                // @ts-ignore
+                input[k] = this.derandomizeInputFile(v);
+            }
+        }
+    }
+    derandomizeInputFile(file) {
+        // Since TypeScript 5.8, a new `lastModified` field has appeared in `File.state: FileState {}` when snapshotting.
+        // The problem is that this value is a timestamp that changes everytime we execute the tests.
+        // Creating a `specificAssertion` just for that would be cumbersome.
+        // Hence the transform of the `File` into a deterministic `Object` for easy snapshotting.
+        return {
+            name: file.name,
+            size: file.size,
+            type: file.type,
+        };
     }
 };
 UCExecutor = UCExecutor_1 = __decorate([

package/package.json

@@ -1,12 +1,22 @@
 {
     "name": "libmodulor",
     "description": "An opinionated TypeScript library to create business oriented applications",
-    "version": "0.6.1",
+    "version": "0.7.0",
     "license": "LGPL-3.0",
     "author": "Chafik H'nini <chafik.hnini@gmail.com>",
     "homepage": "https://github.com/c100k/libmodulor#readme",
     "bugs": "https://github.com/c100k/libmodulor/issues",
-    "keywords": ["library", "typescript", "business application", "use case", "app", "product", "target", "auto-test", "auto-documentation"],
+    "keywords": [
+        "library",
+        "typescript",
+        "business application",
+        "use case",
+        "app",
+        "product",
+        "target",
+        "auto-test",
+        "auto-documentation"
+    ],
     "type": "module",
     "module": "./dist/esm/index.js",
     "exports": {
@@ -54,9 +64,16 @@
         }
     },
     "bin": "./dist/esm/products/Helper/index.js",
+    "scripts": {
+        "lint": "biome check --write .",
+        "lint:ci": "biome check"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "^1.9.4"
+    },
     "peerDependencies": {
         "@hono/node-server": "^1.13.8",
-        "@modelcontextprotocol/sdk": "^1.6.0",
+        "@modelcontextprotocol/sdk": "^1.6.1",
         "@stricli/core": "^1.1.1",
         "buffer": "^6.0.3",
         "cookie-parser": "^1.4.7",
@@ -74,7 +91,7 @@
         "react-native": "^0.78.0",
         "reflect-metadata": "^0.2.2",
         "sqlite3": "^5.1.7",
-        "typescript": "^5.7.3",
+        "typescript": "^5.8.2",
         "vite": "^6.2.0",
         "vitest": "^3.0.7"
     },

package/.github/ISSUE_TEMPLATE/generic-issue.md

@@ -1,16 +0,0 @@
----
-name: Generic Issue
-about: Describe this issue template's purpose here.
-title: ''
-labels: ''
-assignees: ''
-
----
-
-## Problem
-
-<!-- State the problem clearly with as much details as you can. It can be a new feature request or a bug. Either way, there should be a clear problem -->
-
-## Potential Solution(s)
-
-<!-- If you have ideas, feel free to suggest them, we love it. We'll discuss the solutions and find the best one for everyone -->

package/.github/dependabot.yml

@@ -1,19 +0,0 @@
-# To get started with Dependabot version updates, you'll need to specify which
-# package ecosystems to update and where the package manifests are located.
-# Please see the documentation for all configuration options:
-# https://help.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
-
-version: 2
-updates:
-  - package-ecosystem: "npm"
-    directory: "/"
-    schedule:
-      interval: "weekly"
-    ignore:
-      - dependency-name: "inversify"
-        versions: ["7.x"]
-    groups:
-      dev:
-        dependency-type: "development"
-      prod:
-        dependency-type: "production"