@lakutata/template-cli 3.0.0-beta.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2023-present Lakutata
+
+All rights reserved
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# @lakutata/template-cli
+
+The command line template of the [lakutata](https://github.com/lakutata/lakutata) projects: the actions of its controllers
+are the commands of a tool (the commander adapter), built into executables which run without Node.js (`lakutata package
+exe`, for this platform and the others), or bundled into one JavaScript file run by node (`lakutata package bundle`). The
+project is a workspace: the tool is its app package, the packages it uses (native addons…) are next to it.
+
+```bash
+npx @lakutata/cli create --name my-tool --template cli
+```
+
+The files of the project are in `template/`; `lakutata create` fills `{$APP_NAME}`, `{$APP_ID}`, `{$APP_DESC}`,
+`{$APP_AUTHOR}` and `{$APP_LICENSE}`, and renames `_gitignore` to `.gitignore`.

package/features/i18n/packages/app/package.json

@@ -0,0 +1,6 @@
+{
+  "scripts": {
+    "i18n:check": "lakutata i18n check --dir src/locales",
+    "i18n:types": "lakutata i18n types --dir src/locales"
+  }
+}

package/features/i18n/packages/app/src/locales/en.json

@@ -0,0 +1,5 @@
+{
+  "greeting": {
+    "hello": "Hello, {name}!"
+  }
+}

package/features/i18n/packages/app/src/locales/zh-CN.json

@@ -0,0 +1,5 @@
+{
+  "greeting": {
+    "hello": "你好，{name}！"
+  }
+}

package/features/i18n/packages/app/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "compilerOptions": {
+    "resolveJsonModule": true
+  }
+}

package/features/installer/Dockerfile.installer

@@ -0,0 +1,10 @@
+# The installers of Linux (npm run package:linux), made on Linux: the packages of the configuration (lakutata.installer
+# of the package.json) in dist/installer. The ones of another architecture: docker buildx build --platform linux/amd64 ...
+# The apk packages are made on Alpine (node:22-alpine), with Bun when the application has native addons.
+FROM node:22-bookworm AS build
+WORKDIR /project
+COPY . .
+RUN (npm ci --no-audit --no-fund || npm install --no-audit --no-fund) && npm run build && npm run package -w app -- --outdir /installer
+
+FROM scratch
+COPY --from=build /installer /

package/features/installer/_dockerignore

@@ -0,0 +1,12 @@
+.git
+node_modules
+**/node_modules
+**/build
+*.log
+.env
+.env.*
+**/.next
+**/.nuxt
+**/.output
+dist
+**/dist

package/features/installer/package.json

@@ -0,0 +1,6 @@
+{
+  "scripts": {
+    "package:host": "npm run build && npm run package -w app -- --outdir ../../dist/installer",
+    "package:linux": "docker buildx build --file Dockerfile.installer --output type=local,dest=dist/installer ."
+  }
+}

package/features/installer/packages/app/package.json

@@ -0,0 +1,16 @@
+{
+  "scripts": {
+    "package": "lakutata package installer"
+  },
+  "lakutata": {
+    "installer": {
+      "linux": {
+        "targets": [
+          "deb",
+          "rpm",
+          "tar.gz"
+        ]
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@lakutata/template-cli",
+  "version": "3.0.0-beta.0",
+  "description": "The command line template of the lakutata projects: a command line tool built into executables which run without Node.js.",
+  "keywords": [
+    "lakutata",
+    "lakutata-template"
+  ],
+  "license": "MIT",
+  "files": [
+    "template",
+    "features",
+    "README.md",
+    "LICENSE"
+  ],
+  "lakutata": {
+    "template": "cli",
+    "features": {
+      "i18n": "The messages in several languages (lakutata/com/i18n): src/locales, the language of each request",
+      "installer": "The installers of the application (lakutata package installer): deb, rpm and tar.gz on Linux (npm run package:linux in Docker), pkg and tar.gz on macOS, nsis, msi and zip on Windows, its program in the PATH"
+    }
+  }
+}

package/template/README.md

@@ -0,0 +1,89 @@
+# {$APP_NAME}
+
+{$APP_DESC}
+
+A [lakutata](https://github.com/lakutata/lakutata) command line tool: the actions of its controllers are its commands.
+It is built into an executable which runs without Node.js. The project is a workspace: `packages/app` is the tool, the
+other packages are the ones it uses (`npx lakutata add <name>`: a package of TypeScript, or a native addon with
+`--native`).
+
+```bash
+npm run build                           # build the packages, in the order of their dependencies: node packages/app/build/App.js greet --name you
+npm test                                # the tests of the packages
+npm run package:exe                     # the executable of this platform: dist/{$APP_ID} (dist/{$APP_ID}.exe on Windows)
+./dist/{$APP_ID} greet --name you       # run a command (--help lists them)
+npm run package:bundle                  # one JavaScript file with the dependencies: node dist/{$APP_ID}.cjs greet --name you
+```
+
+- `packages/app/src/App.ts` starts the tool;
+- `packages/app/src/config/Config.ts` declares its components and the command line adapter (its name, its description
+  and its version come from `packages/app/package.json`);
+- `packages/app/src/controllers/` holds the controllers: each `@CLIAction` is a command, whose options are the properties
+  of its DTO (`packages/app/src/dtos/`), validated before the action runs. In a terminal, the missing required options
+  are asked.
+
+`npm link -w app` installs the command `{$APP_ID}` on this machine; `npm publish -w app` (named, without
+`"private": true`) shares it.
+
+## The executables and the bundle
+
+`lakutata package bundle` bundles the compiled tool and its dependencies into `dist/{$APP_ID}.cjs`, run by node without
+`node_modules`. `lakutata package exe` embeds the bundle into the Node.js binary running it (the single executable
+applications of Node.js): the executable runs without Node.js installed, the Node.js embedded is the version which makes
+it.
+
+- The native addons (`.node` files) are handled: next to the bundle (`dist/{$APP_ID}.native/`, distributed with it),
+  embedded in the executable, which extracts them at its first run into its cache directory (`LAKUTATA_NATIVE_DIR`
+  changes it).
+- The bundle is a CommonJS module: no top-level `await` in the sources (await in an async function).
+- The executables of macOS are signed ad hoc. The executables of Windows keep the signature of Node.js, which does not
+  match anymore: sign them before distributing them.
+
+<!-- @if installer -->
+## The installers
+
+`npm run package:host` makes the installers of the platform it runs on (`lakutata package installer`, configured by the
+`lakutata.installer` of `packages/app/package.json`) in `dist/installer`, the command `{$APP_ID}` in the PATH:
+
+- Linux: the deb, rpm and tar.gz packages installing the tool in `/opt/{$APP_ID}`; `npm run package:linux` makes them in
+  Docker (`Dockerfile.installer`) on any platform, `--platform linux/amd64` the ones of another architecture.
+- macOS: the pkg package installing it in `/usr/local/lib/{$APP_ID}` (`sudo /usr/local/lib/{$APP_ID}/uninstall` removes it).
+- Windows: the installer of NSIS and the package of Windows Installer (msi) installing it in `C:\Program Files\{$APP_ID}`.
+
+<!-- @end -->
+## The other platforms
+
+`npm run package:exe` makes the executable of the platform it runs on: the executables of the other platforms are made on them
+(their native addons are built there, and they are tried there). A CI makes them all, for example GitHub Actions
+(`.github/workflows/build.yml`):
+
+```yaml
+name: build
+on: push
+jobs:
+  build:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, ubuntu-24.04-arm, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm ci
+      - run: npm test
+      - run: npm run package:exe
+      - uses: actions/upload-artifact@v4
+        with:
+          name: {$APP_ID}-${{ runner.os }}-${{ runner.arch }}
+          path: dist/
+```
+
+The Linux architectures are also made on any machine with Docker, in a container of the architecture (the project is
+copied into it: the `node_modules` of the project are not changed):
+
+```bash
+docker run --rm --platform linux/arm64 -v "$PWD":/source:ro -v "$PWD/dist":/source/dist node:22 sh -c \
+  "cp -r /source /project && cd /project && rm -rf node_modules && npm ci && npm run package:exe && cp dist/{$APP_ID} /source/dist/{$APP_ID}-linux-arm64"
+```

package/template/_gitignore

@@ -0,0 +1,13 @@
+node_modules
+build
+dist
+*.log
+.env
+.env.*
+.DS_Store
+.idea
+.vscode
+.next
+next-env.d.ts
+.nuxt
+.output

package/template/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "{$APP_ID}-workspace",
+  "version": "0.0.1",
+  "private": true,
+  "workspaces": [
+    "packages/*"
+  ],
+  "scripts": {
+    "build": "lakutata run rebuild",
+    "test": "lakutata run test",
+    "start": "npm start -w app",
+    "package:bundle": "npm run build && npm run package:bundle -w app -- --outfile ../../dist/{$APP_ID}.cjs",
+    "package:exe": "npm run build && npm run package:exe -w app -- --outdir ../../dist",
+    "version:patch": "lakutata version patch --yes"
+  },
+  "devDependencies": {
+    "@lakutata/builder": "^{$LAKUTATA_VERSION}",
+    "@lakutata/cli": "^{$LAKUTATA_VERSION}",
+    "@types/node": "^22.0.0",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/template/packages/app/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "app",
+  "version": "0.0.1",
+  "description": "{$APP_DESC}",
+  "author": "{$APP_AUTHOR}",
+  "license": "{$APP_LICENSE}",
+  "private": true,
+  "type": "module",
+  "main": "build/App.js",
+  "bin": {
+    "{$APP_ID}": "build/App.js"
+  },
+  "files": [
+    "build",
+    "!build/tests"
+  ],
+  "scripts": {
+    "clean": "lakutata clean",
+    "build": "tsc",
+    "rebuild": "npm run clean && npm run build",
+    "start": "node build/App.js",
+    "test": "node --test \"build/tests/**/*.spec.js\"",
+    "package:bundle": "lakutata package bundle",
+    "package:exe": "lakutata package exe"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.7.2",
+    "commander": "^15.0.0",
+    "lakutata": "^{$LAKUTATA_VERSION}"
+  },
+  "lakutata": {
+    "icon": "../resources/logo.png"
+  }
+}

package/template/packages/app/src/App.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import {Application} from 'lakutata'
+import {installerConfig} from './config/Config.js'
+
+Application.run(installerConfig())

package/template/packages/app/src/config/Config.ts

@@ -0,0 +1,36 @@
+import type {ApplicationOptions} from 'lakutata'
+import {buildEntrypoints} from 'lakutata/com/entrypoint'
+import {commanderCLIEntrypoint} from 'lakutata/adapter/commander'
+import manifest from '../../package.json' with {type: 'json'}
+import {ExampleController} from '../controllers/ExampleController.js'
+//@if i18n
+import {buildI18nOptions, I18nMiddleware} from 'lakutata/com/i18n'
+import en from '../locales/en.json' with {type: 'json'}
+import zhCN from '../locales/zh-CN.json' with {type: 'json'}
+//@end
+
+/**
+ * The options of the tool
+ */
+export function installerConfig(): ApplicationOptions {
+    return {
+        id: '{$APP_ID}',
+        name: '{$APP_NAME}',
+        components: {
+            //@if i18n
+            //The messages of the languages (src/locales), bundled with the code; created by the first request
+            i18n: buildI18nOptions({messages: {'en': en, 'zh-CN': zhCN}}),
+            //@end
+            entrypoint: buildEntrypoints({
+                controllers: [ExampleController],
+                //@if i18n
+                //The messages in the language of its environment (LANG)
+                middlewares: [I18nMiddleware],
+                //@end
+                //The actions of the controllers are the commands; the missing required options are asked in a terminal
+                cli: commanderCLIEntrypoint({bin: '{$APP_ID}', description: manifest.description, version: manifest.version})
+            })
+        },
+        bootstrap: ['entrypoint']
+    }
+}

package/template/packages/app/src/controllers/ExampleController.ts

@@ -0,0 +1,32 @@
+import {Controller} from 'lakutata/com/entrypoint'
+import {CLIAction} from 'lakutata/decorator/ctrl'
+import {GreetDTO} from '../dtos/GreetDTO.js'
+//@if i18n
+import {Inject} from 'lakutata/decorator/di'
+import {Translator} from 'lakutata/com/i18n'
+//@end
+
+export class ExampleController extends Controller {
+    //@if i18n
+
+    /**
+     * The messages of the language of the request
+     */
+    @Inject(Translator)
+    protected readonly i18n: Translator
+    //@end
+
+    /**
+     * {$APP_ID} greet --name you: the result is printed
+     * @param input
+     */
+    @CLIAction('greet', GreetDTO, {description: 'Greet someone'})
+    public async greet(input: GreetDTO): Promise<string> {
+        //@if i18n
+        const greeting: string = this.i18n.t('greeting.hello', {name: input.name})
+        //@else
+        const greeting: string = `Hello, ${input.name}!`
+        //@end
+        return Array(input.times).fill(input.loud ? greeting.toUpperCase() : greeting).join('\n')
+    }
+}

package/template/packages/app/src/dtos/GreetDTO.ts

@@ -0,0 +1,16 @@
+import {DTO} from 'lakutata'
+import {Expect} from 'lakutata/decorator/dto'
+
+/**
+ * The options of the command: --name <name> [--times <times>] [--loud]
+ */
+export class GreetDTO extends DTO {
+    @Expect(DTO.String().required().description('Who is greeted'))
+    public name: string
+
+    @Expect(DTO.Number().integer().min(1).max(10).optional().default(1).description('How many times'))
+    public times: number
+
+    @Expect(DTO.Boolean().optional().default(false).description('Greet loudly'))
+    public loud: boolean
+}

package/template/packages/app/src/tests/App.spec.ts

@@ -0,0 +1,66 @@
+import {describe, it} from 'node:test'
+//@if i18n
+import {before} from 'node:test'
+//@end
+import assert from 'node:assert'
+import {execFile, type ExecFileException} from 'node:child_process'
+import {readFileSync} from 'node:fs'
+import {fileURLToPath} from 'node:url'
+
+/**
+ * The compiled tool
+ */
+const TOOL: string = fileURLToPath(new URL('../App.js', import.meta.url))
+
+/**
+ * Run the tool with arguments
+ * @param args
+ */
+function tool(...args: string[]): Promise<{ code: number, stdout: string, stderr: string }> {
+    return new Promise((resolve: (result: { code: number, stdout: string, stderr: string }) => void): void => {
+        execFile(process.execPath, [TOOL, ...args], (error: ExecFileException | null, stdout: string, stderr: string): void => resolve({code: error ? (typeof error.code === 'number' ? error.code : 1) : 0, stdout: stdout, stderr: stderr}))
+    })
+}
+
+describe('{$APP_NAME}', (): void => {
+    //@if i18n
+
+    //The tool answers in the language of its environment: English for the tests
+    before((): void => {
+        process.env.LC_ALL = 'en_US.UTF-8'
+    })
+    //@end
+
+    it('greets', async (): Promise<void> => {
+        const result = await tool('greet', '--name', 'you')
+        assert.strictEqual(result.code, 0, result.stderr)
+        assert.strictEqual(result.stdout.trim(), 'Hello, you!')
+    })
+
+    //@if i18n
+    it('greets in the language of its environment', async (): Promise<void> => {
+        process.env.LC_ALL = 'zh_CN.UTF-8'
+        try {
+            assert.strictEqual((await tool('greet', '--name', 'you')).stdout.trim(), '你好，you！')
+        } finally {
+            process.env.LC_ALL = 'en_US.UTF-8'
+        }
+    })
+
+    //@end
+    it('greets with the options', async (): Promise<void> => {
+        const result = await tool('greet', '--name', 'you', '--times', '2', '--loud')
+        assert.strictEqual(result.stdout.trim(), 'HELLO, YOU!\nHELLO, YOU!')
+    })
+
+    it('refuses an invalid option', async (): Promise<void> => {
+        const result = await tool('greet', '--name', 'you', '--times', '11')
+        assert.notStrictEqual(result.code, 0)
+        assert.match(result.stderr, /times/)
+    })
+
+    it('shows its version', async (): Promise<void> => {
+        const {version} = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'))
+        assert.strictEqual((await tool('--version')).stdout.trim(), version)
+    })
+})

package/template/packages/app/src/types/package.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The package.json of the project, imported by the application for its name and its version: tsc keeps the import, node
+ * reads the file (build/ and src/ are next to it), the bundles embed it
+ */
+declare module '*/package.json' {
+    const manifest: {
+        name: string
+        version: string
+        description?: string
+    }
+    export = manifest
+}

package/template/packages/app/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "ESNext.Disposable"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "rootDir": "src",
+    "outDir": "build",
+    "types": ["node"],
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "useDefineForClassFields": false,
+    "strict": true,
+    "strictPropertyInitialization": false,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "sourceMap": true
+  },
+  "include": ["src"]
+}

package/template/packages/resources/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "resources",
+  "version": "0.0.1",
+  "private": true,
+  "description": "The resources of the application: its icon (logo.png, lakutata.icon of the app package), made into the icons of each platform"
+}