@lakutata/cli 3.1.1 → 3.1.2

package/README.md

@@ -57,7 +57,8 @@ the command fails.
 A template package keeps its files in its `template/` directory. npm packages cannot hold some files under their real
 names, so `_gitignore`, `_npmrc`… are renamed `.gitignore`, `.npmrc`… when the project is created. The text files are
 filled with the information of the project: `{$APP_NAME}`, `{$APP_ID}`, `{$APP_DESC}`, `{$APP_AUTHOR}`,
-`{$APP_LICENSE}` and `{$LAKUTATA_VERSION}` (the version of the framework).
+`{$APP_LICENSE}` and `{$LAKUTATA_VERSION}` (the minor version of the framework, `3.1.0` for 3.1.2: a patch releases
+only the packages it changes, so `^{$LAKUTATA_VERSION}` finds every package of lakutata).
 
 A template can have optional features, which `lakutata create --with <features>` enables (or which the user chooses in
 a terminal):
@@ -213,6 +214,34 @@ Packages are still published with `npm publish -w <package>` (the packages `laku
 `lerna.json` with `"version": "independent"` cannot be bumped), write changelogs from the commits or cache builds:
 workspaces that need these keep lerna (or nx, turborepo) alongside it.
 
+## Native libraries
+
+### `lakutata ffi generate <header>`
+
+Generate the class of a native library of `@lakutata/ffi` from its C header: its declarations, a property by function
+with its TypeScript type, an interface by struct and union, its integer macros as constants. The header is run through
+the preprocessor of the C compiler (`cc -E`; `cl /P` on Windows, in the Developer Command Prompt of Visual Studio); the
+declarations of the library are kept (the ones of the header, and of the headers of its directory unless it is a
+directory of the system), with the types of the system they use. The functions are then checked against the library:
+the ones it does not export, or that cannot be called (a `va_list` parameter), are left out. The command lists what
+it left out and why. The tool loads `@lakutata/ffi` from the project: install it there.
+
+| Option | |
+|---|---|
+| `--library <name or file>` | the library the functions are checked against: a name, as `@Library` takes it, or a file; the name of the header by default (`sqlite3.h`: `sqlite3`; zlib needs `--library z`). When it cannot be loaded, the class is generated without the check, with a warning |
+| `--class-name <name>` | the name of the class, the name of the header in PascalCase by default |
+| `--out <file>` | the file written, `<class>.ts` in the current directory by default |
+| `--force` | replace the file when it exists |
+| `--include <directories...>` | the directories of the headers it includes (`-I`) |
+| `--define <macros...>` | the macros defined before it: `NAME` or `NAME=value` (`-D`) |
+| `--own <directories...>` | more directories whose headers are the ones of the library |
+| `--compiler <compiler>` | the C compiler whose preprocessor reads the header: `cc`, `gcc`, `clang`, `cl` (the one of `CC` by default, else `cl` on Windows and `cc` elsewhere) |
+| `--no-check` | do not check the functions against the library |
+
+The class is generated for the platform the command runs on. A header does not say which pointers are output
+parameters, nor which functions block: mark them in the file generated (`_Out_`, `{async: true}`). See the guide to
+native libraries ([FFI](https://lakutata.com/guide/FFI), section 9).
+
 ## Bundles and executables
 
 These commands pack the application in the current directory, which must be compiled first (by `tsc`, which emits the

package/README.zh-CN.md

@@ -42,7 +42,7 @@ lakutata create --name my-service --template service --with i18n --yes
 
 官方模板取与工具主版本号相同的最新正式版。下载过的模板会缓存起来：连不上仓库时，使用缓存中这个主版本的最新版本；缓存中也没有时，命令失败。
 
-模板包把文件放在它的 `template/` 目录中。有些文件无法以真实的文件名放进 npm 包，所以 `_gitignore`、`_npmrc` 等文件会在创建项目时改名为 `.gitignore`、`.npmrc` 等。文本文件中会填入项目的信息：`{$APP_NAME}`、`{$APP_ID}`、`{$APP_DESC}`、`{$APP_AUTHOR}`、`{$APP_LICENSE}` 和 `{$LAKUTATA_VERSION}`（框架的版本）。
+模板包把文件放在它的 `template/` 目录中。有些文件无法以真实的文件名放进 npm 包，所以 `_gitignore`、`_npmrc` 等文件会在创建项目时改名为 `.gitignore`、`.npmrc` 等。文本文件中会填入项目的信息：`{$APP_NAME}`、`{$APP_ID}`、`{$APP_DESC}`、`{$APP_AUTHOR}`、`{$APP_LICENSE}` 和 `{$LAKUTATA_VERSION}`（框架的次版本，比如框架是 3.1.2 时为 `3.1.0`：补丁版只发布改动过的包，写成 `^{$LAKUTATA_VERSION}` 才能找到 lakutata 的每个包）。
 
 模板可以有可选功能，由 `lakutata create --with <features>` 启用（或者由用户在终端里选择）：
 
@@ -130,6 +130,26 @@ lakutata create --name my-service --template service --with i18n --yes
 
 包仍然用 `npm publish -w <package>` 发布（`lakutata add` 创建的包是私有的：请先删掉 `"private": true`）。工具只读写 `lerna.json` 中的 `version`：包来自根目录 `package.json` 的 `workspaces`，或者 `pnpm-workspace.yaml`。它不支持给各个包分别设置版本号（`"version": "independent"` 的 `lerna.json` 无法递增版本），不根据提交生成变更日志，也不缓存构建结果：需要这些功能的工作区可以同时保留 lerna（或 nx、turborepo）。
 
+## 原生库
+
+### `lakutata ffi generate <header>`
+
+根据 C 头文件生成 `@lakutata/ffi` 原生库的类：包括它的声明、每个函数一个带 TypeScript 类型的属性、每个结构体和联合一个接口，整数宏作为常量。头文件先经过 C 编译器的预处理器（`cc -E`；在 Windows 上是 `cl /P`，请在 Visual Studio 的开发者命令提示符里运行）；保留库自己的声明（头文件里的，以及它所在目录里其他头文件的，这个目录是系统目录时除外），以及这些声明用到的系统类型。然后用库检查这些函数：库里没有导出的函数和不能调用的函数（参数是 `va_list`）会被去掉。命令会列出去掉了哪些声明，以及原因。工具从项目里加载 `@lakutata/ffi`：请把它装在项目里。
+
+| 选项 | |
+|---|---|
+| `--library <name or file>` | 用来检查函数的库：`@Library` 接受的库名，或一个文件；默认和头文件同名（`sqlite3.h` 对应 `sqlite3`；zlib 要写 `--library z`）。库加载不了时，照样生成类，只是不做检查，并给出警告 |
+| `--class-name <name>` | 类的名称，默认是头文件名的 PascalCase 形式 |
+| `--out <file>` | 要写入的文件，默认是当前目录下的 `<类名>.ts` |
+| `--force` | 文件已存在时覆盖它 |
+| `--include <directories...>` | 头文件引用的其他头文件所在的目录（`-I`） |
+| `--define <macros...>` | 在头文件之前定义的宏：`NAME` 或 `NAME=value`（`-D`） |
+| `--own <directories...>` | 其他属于这个库的头文件的目录 |
+| `--compiler <compiler>` | 用来预处理头文件的 C 编译器：`cc`、`gcc`、`clang`、`cl`（默认取 `CC` 环境变量，没有时在 Windows 上是 `cl`，其他系统上是 `cc`） |
+| `--no-check` | 不用库检查函数 |
+
+类是针对运行命令的平台生成的。头文件看不出哪些指针是输出参数，也看不出哪些函数会阻塞：请在生成的文件里自己标出来（`_Out_`、`{async: true}`）。见原生库的指南（[FFI](https://lakutata.com/zh/guide/FFI) 第 9 节）。
+
 ## 单文件包和可执行文件
 
 这些命令打包当前目录中的应用，应用必须先编译好（用 `tsc`，它会生成装饰器的元数据）。实际的工作由 `@lakutata/builder` 完成：优先用项目中安装的那份（`npm install --save-dev @lakutata/builder`，需要打包应用的模板都是这样做的），否则用随工具一起安装的那份（全局安装工具时不会带上它，因为它只是工具的可选 peer 依赖）。脚本也可以调用它的函数（`bundleProject`、`buildExecutable`）来打包应用。

package/dist/esm/Config.js

@@ -8,13 +8,14 @@ import { WorkspaceController } from './controllers/WorkspaceController.js';
 import { PackController } from './controllers/PackController.js';
 import { MigrationController } from './controllers/MigrationController.js';
 import { NativeController } from './controllers/NativeController.js';
+import { FFIController } from './controllers/FFIController.js';
 import { I18nController } from './controllers/I18nController.js';
 import { LANGUAGE_VARIABLE, LanguageMiddleware } from './lib/Language.js';
 import { toolPackage } from './lib/Versions.js';
 /**
  * The controllers of the commands of the tool
  */
-export const CONTROLLERS = [CommandLineController, WorkspaceController, PackController, MigrationController, NativeController, I18nController];
+export const CONTROLLERS = [CommandLineController, WorkspaceController, PackController, MigrationController, NativeController, FFIController, I18nController];
 /**
  * The messages of the tool in the languages besides English (its texts in the code): its help, its prompts
  */
@@ -22,7 +23,8 @@ export const CONTROLLERS = [CommandLineController, WorkspaceController, PackCont
  * The groups of commands: lakutata package --help lists the commands of the group package
  */
 export const COMMAND_GROUPS = {
-    package: 'Package the compiled application: into one JavaScript file, an executable or its installers'
+    package: 'Package the compiled application: into one JavaScript file, an executable or its installers',
+    ffi: 'Generate the classes of the native libraries of @lakutata/ffi from their C headers'
 };
 export const MESSAGES = { 'zh-CN': zhCN, 'zh-TW': zhTW };
 /**

package/dist/esm/controllers/FFIController.js

@@ -0,0 +1,54 @@
+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);
+};
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { Controller } from 'lakutata/com/entrypoint';
+import { CLIAction } from 'lakutata/decorator/ctrl';
+import { FFIGenerateDTO } from '../dtos/FFIGenerateDTO.js';
+import { loadGenerator } from '../lib/FFI.js';
+import { done, warn } from '../lib/Output.js';
+/**
+ * The commands of the native libraries (@lakutata/ffi)
+ */
+export class FFIController extends Controller {
+    async generate(input) {
+        const generator = await loadGenerator(process.cwd());
+        const { className, code, report } = await generator.generateNativeLibrary({
+            header: input.header,
+            library: input.library,
+            className: input.className,
+            include: input.include,
+            define: input.define,
+            own: input.own,
+            compiler: input.compiler,
+            check: input.check
+        });
+        const file = path.resolve(input.out ?? `${className}.ts`);
+        if (existsSync(file) && !input.force)
+            throw new Error(`${path.relative(process.cwd(), file)} exists: give --force to replace it`);
+        mkdirSync(path.dirname(file), { recursive: true });
+        writeFileSync(file, code);
+        const count = (number, noun) => `${number} ${noun}${number === 1 ? '' : 's'}`;
+        done(`Generated ${path.relative(process.cwd(), file)} (${className}): ${count(report.functions, 'function')}, ${count(report.variables, 'variable')}, ${count(report.interfaces, 'interface')}, ${count(report.constants, 'constant')}${report.library ? `, checked against ${report.library}` : ''}`);
+        if (!report.library)
+            warn(input.check ? `The functions were not checked against the library: ${report.unchecked}; give it with --library` : 'The functions were not checked against the library (--no-check)');
+        if (report.skipped.length)
+            warn(`Left out ${count(report.skipped.length, 'declaration')} of the library:`);
+        for (const skipped of report.skipped)
+            warn(`  ${skipped.name}${skipped.file ? ` (${path.relative(process.cwd(), skipped.file)}:${skipped.line})` : ''}: ${skipped.reason}`);
+        return undefined;
+    }
+}
+__decorate([
+    CLIAction('ffi generate <header>', FFIGenerateDTO, { description: 'Generate the class of a native library from its C header: a property by function, an interface by struct, the constants, with their TypeScript types' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [FFIGenerateDTO]),
+    __metadata("design:returntype", Promise)
+], FFIController.prototype, "generate", null);

package/dist/esm/dtos/FFIGenerateDTO.js

@@ -0,0 +1,53 @@
+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);
+};
+import { DTO } from 'lakutata';
+import { Expect } from 'lakutata/decorator/dto';
+export class FFIGenerateDTO extends DTO {
+}
+__decorate([
+    Expect(DTO.String().required().description('The C header of the library')),
+    __metadata("design:type", String)
+], FFIGenerateDTO.prototype, "header", void 0);
+__decorate([
+    Expect(DTO.String().optional().description('The library its functions are checked against: a name, as @Library takes it, or a file (the name of the header by default)')),
+    __metadata("design:type", String)
+], FFIGenerateDTO.prototype, "library", void 0);
+__decorate([
+    Expect(DTO.String().optional().description('The name of the class (the name of the header in PascalCase by default)')),
+    __metadata("design:type", String)
+], FFIGenerateDTO.prototype, "className", void 0);
+__decorate([
+    Expect(DTO.String().optional().description('The TypeScript file written (<class>.ts in the current directory by default)')),
+    __metadata("design:type", String)
+], FFIGenerateDTO.prototype, "out", void 0);
+__decorate([
+    Expect(DTO.Array(DTO.String()).optional().description('The directories of the headers it includes (-I)')),
+    __metadata("design:type", Array)
+], FFIGenerateDTO.prototype, "include", void 0);
+__decorate([
+    Expect(DTO.Array(DTO.String()).optional().description('The macros defined before it: NAME or NAME=value (-D)')),
+    __metadata("design:type", Array)
+], FFIGenerateDTO.prototype, "define", void 0);
+__decorate([
+    Expect(DTO.Array(DTO.String()).optional().description('More directories whose headers are the ones of the library (the header already is, and so are the headers of its directory unless that is a directory of the system)')),
+    __metadata("design:type", Array)
+], FFIGenerateDTO.prototype, "own", void 0);
+__decorate([
+    Expect(DTO.String().optional().description('The C compiler whose preprocessor reads the header: cc, gcc, clang, cl (the one of CC by default, else cl on Windows and cc elsewhere)')),
+    __metadata("design:type", String)
+], FFIGenerateDTO.prototype, "compiler", void 0);
+__decorate([
+    Expect(DTO.Boolean().optional().default(true).description('Check the functions and the variables against the library, leaving out the ones it cannot give')),
+    __metadata("design:type", Boolean)
+], FFIGenerateDTO.prototype, "check", void 0);
+__decorate([
+    Expect(DTO.Boolean().optional().default(false).description('Replace the file when it exists')),
+    __metadata("design:type", Boolean)
+], FFIGenerateDTO.prototype, "force", void 0);

package/dist/esm/lib/FFI.js

@@ -0,0 +1,21 @@
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+/**
+ * The generator of a project: the one of the @lakutata/ffi installed in the project (its node_modules, the ones of its
+ * workspace), else the one installed with the tool
+ * @param project
+ */
+export async function loadGenerator(project) {
+    for (const base of [path.join(project, 'package.json'), import.meta.url]) {
+        let entry;
+        try {
+            entry = createRequire(base).resolve('@lakutata/ffi/generator');
+        }
+        catch {
+            continue;
+        }
+        return await import(pathToFileURL(entry).href);
+    }
+    throw new Error('@lakutata/ffi is not installed: install it in the project (npm install @lakutata/ffi)');
+}

package/dist/esm/lib/ProjectCreator.js

@@ -17,7 +17,7 @@ import { TemplateCatalog } from './TemplateCatalog.js';
 import { runCommand } from './Processes.js';
 import { done, step, warn } from './Output.js';
 import { applyFeatureBlocks, applyFeatureFiles, projectPath } from './TemplateFeatures.js';
-import { frameworkVersion } from './Versions.js';
+import { templateVersion } from './Versions.js';
 /**
  * The directories of a template which are not copied
  */
@@ -154,7 +154,7 @@ let ProjectCreator = class ProjectCreator extends Component {
             $APP_DESC: plan.description,
             $APP_AUTHOR: plan.author,
             $APP_LICENSE: plan.license,
-            $LAKUTATA_VERSION: frameworkVersion()
+            $LAKUTATA_VERSION: templateVersion()
         }, new Set(plan.features));
         done('Project information filled');
         if (plan.packageManager !== 'none') {

package/dist/esm/lib/Versions.js

@@ -15,6 +15,16 @@ export function toolPackage() {
 export function frameworkVersion() {
     return require('lakutata/package.json').version;
 }
+/**
+ * The version of the packages of lakutata written in the projects created, after a ^: the minor version of the
+ * framework (3.1.0 for 3.1.2), since a patch releases only the packages it changes; a prerelease as it is, since all
+ * the packages are released with it
+ */
+export function templateVersion() {
+    const version = frameworkVersion();
+    const release = /^(\d+)\.(\d+)\.\d+$/.exec(version);
+    return release ? `${release[1]}.${release[2]}.0` : version;
+}
 /**
  * The latest version of a package on the registry, undefined when it cannot be fetched
  * @param name

package/dist/esm/locales/zh-CN.json

@@ -132,6 +132,26 @@
                     "target": "要修改的构建目标（默认是唯一的那个）"
                 }
             },
+            "ffi": {
+                "description": "根据 C 头文件生成 @lakutata/ffi 原生库的类",
+                "generate": {
+                    "description": "根据 C 头文件生成原生库的类：每个函数一个属性，每个结构体一个接口，加上常量，都带有 TypeScript 类型",
+                    "arguments": {
+                        "header": "库的 C 头文件"
+                    },
+                    "options": {
+                        "library": "用来检查函数的库：@Library 接受的库名，或一个文件（默认按头文件的名字）",
+                        "className": "类的名称（默认是头文件名的 PascalCase 形式）",
+                        "out": "要写入的 TypeScript 文件（默认是当前目录下的 <类名>.ts）",
+                        "include": "头文件引用的其他头文件所在的目录（-I）",
+                        "define": "在头文件之前定义的宏：NAME 或 NAME=value（-D）",
+                        "own": "其他属于这个库的头文件的目录（头文件本身算库的；它所在的目录不是系统目录时，目录里的头文件也算）",
+                        "compiler": "用来预处理头文件的 C 编译器：cc、gcc、clang、cl（默认取 CC 环境变量，没有时在 Windows 上是 cl，其他系统上是 cc）",
+                        "check": "用库检查函数和变量，去掉库里没有的",
+                        "force": "文件已存在时覆盖它"
+                    }
+                }
+            },
             "i18n": {
                 "description": "检查各语言的翻译、声明键名的类型，或添加一种语言",
                 "arguments": {

package/dist/esm/locales/zh-TW.json

@@ -132,6 +132,26 @@
                     "target": "要修改的建置目標（預設是唯一的那個）"
                 }
             },
+            "ffi": {
+                "description": "根據 C 標頭檔產生 @lakutata/ffi 原生程式庫的類別",
+                "generate": {
+                    "description": "根據 C 標頭檔產生原生程式庫的類別：每個函式一個屬性，每個結構一個介面，加上常數，都帶有 TypeScript 型別",
+                    "arguments": {
+                        "header": "程式庫的 C 標頭檔"
+                    },
+                    "options": {
+                        "library": "用來檢查函式的程式庫：@Library 接受的程式庫名稱，或一個檔案（預設依標頭檔的名稱）",
+                        "className": "類別的名稱（預設是標頭檔名的 PascalCase 形式）",
+                        "out": "要寫入的 TypeScript 檔案（預設是目前目錄下的 <類別名稱>.ts）",
+                        "include": "標頭檔引入的其他標頭檔所在的目錄（-I）",
+                        "define": "在標頭檔之前定義的巨集：NAME 或 NAME=value（-D）",
+                        "own": "其他屬於這個程式庫的標頭檔的目錄（標頭檔本身算程式庫的；它所在的目錄不是系統目錄時，目錄裡的標頭檔也算）",
+                        "compiler": "用來前置處理標頭檔的 C 編譯器：cc、gcc、clang、cl（預設取 CC 環境變數，沒有時在 Windows 上是 cl，其他系統上是 cc）",
+                        "check": "用程式庫檢查函式和變數，去掉程式庫裡沒有的",
+                        "force": "檔案已存在時覆寫它"
+                    }
+                }
+            },
             "i18n": {
                 "description": "檢查各語言的翻譯、宣告鍵名的型別，或新增一種語言",
                 "arguments": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lakutata/cli",
-  "version": "3.1.1",
+  "version": "3.1.2",
   "description": "The command line tool of the lakutata framework: create the projects from the templates, run and version the packages of the workspaces, bundle the applications and make their executables (with @lakutata/builder).",
   "keywords": [
     "lakutata",
@@ -39,18 +39,23 @@
   "dependencies": {
     "@inquirer/prompts": "^8.7.2",
     "commander": "^15.0.0",
-    "lakutata": "3.1.1"
+    "lakutata": "3.1.2"
   },
   "peerDependencies": {
-    "@lakutata/builder": "3.1.1"
+    "@lakutata/builder": "~3.1.1",
+    "@lakutata/ffi": "~3.1.2"
   },
   "peerDependenciesMeta": {
     "@lakutata/builder": {
       "optional": true
+    },
+    "@lakutata/ffi": {
+      "optional": true
     }
   },
   "devDependencies": {
-    "@lakutata/builder": "3.1.1"
+    "@lakutata/builder": "~3.1.1",
+    "@lakutata/ffi": "~3.1.2"
   },
   "engines": {
     "node": "^22.13.0 || >=24.11.0"