@lakutata/cli 2.17.0 → 3.0.0-beta.0

package/dist/esm/lib/Tar.js

@@ -0,0 +1,145 @@
+import { chmod, mkdir, symlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { gunzipSync } from 'node:zlib';
+/**
+ * A text field of a header
+ * @param header
+ * @param offset
+ * @param length
+ */
+function readField(header, offset, length) {
+    const field = header.subarray(offset, offset + length);
+    const end = field.indexOf(0);
+    return field.subarray(0, end < 0 ? length : end).toString('utf8');
+}
+/**
+ * An octal number field of a header
+ * @param header
+ * @param offset
+ * @param length
+ */
+function octal(header, offset, length) {
+    const text = readField(header, offset, length).trim();
+    return text ? parseInt(text, 8) : 0;
+}
+/**
+ * The records of an extended (pax) header
+ * @param data
+ */
+function paxRecords(data) {
+    const records = {};
+    let offset = 0;
+    while (offset < data.length) {
+        const space = data.indexOf(0x20, offset);
+        if (space < 0)
+            break;
+        const length = parseInt(data.subarray(offset, space).toString('utf8'), 10);
+        if (!length)
+            break;
+        const record = data.subarray(space + 1, offset + length - 1).toString('utf8');
+        const equals = record.indexOf('=');
+        if (equals > 0)
+            records[record.slice(0, equals)] = record.slice(equals + 1);
+        offset += length;
+    }
+    return records;
+}
+/**
+ * The entries of a tar archive (ustar, with the long names of pax and GNU)
+ * @param archive
+ */
+export function readTar(archive) {
+    const entries = [];
+    let offset = 0;
+    let longName;
+    let longLink;
+    while (offset + 512 <= archive.length) {
+        const header = archive.subarray(offset, offset + 512);
+        //Two empty blocks end the archive
+        if (header.every((byte) => byte === 0))
+            break;
+        const size = octal(header, 124, 12);
+        const type = readField(header, 156, 1) || '0';
+        const data = archive.subarray(offset + 512, offset + 512 + size);
+        offset += 512 + Math.ceil(size / 512) * 512;
+        if (type === 'x') {
+            const records = paxRecords(data);
+            longName = records.path ?? longName;
+            longLink = records.linkpath ?? longLink;
+            continue;
+        }
+        if (type === 'L') {
+            longName = readField(data, 0, data.length);
+            continue;
+        }
+        if (type === 'K') {
+            longLink = readField(data, 0, data.length);
+            continue;
+        }
+        if (type === 'g')
+            continue;
+        const prefix = readField(header, 345, 155);
+        const name = longName ?? (prefix ? `${prefix}/${readField(header, 0, 100)}` : readField(header, 0, 100));
+        entries.push({ name: name, type: type, mode: octal(header, 100, 8), data: data, linkName: longLink ?? readField(header, 157, 100) });
+        longName = undefined;
+        longLink = undefined;
+    }
+    return entries;
+}
+/**
+ * Extract a gzipped tar archive into a directory
+ * @param archive
+ * @param directory
+ * @param select the path of an entry in the directory, from its path in the archive (without its leading "/"), undefined to skip it
+ * @return the paths of the files extracted, relative to the directory
+ */
+export async function extractTarGz(archive, directory, select = (name) => name) {
+    const root = path.resolve(directory);
+    const files = [];
+    for (const entry of readTar(gunzipSync(archive))) {
+        const selected = select(entry.name.split('/').filter((part) => !!part).join('/'));
+        if (!selected)
+            continue;
+        const target = path.resolve(root, selected);
+        //An entry cannot be written outside of the directory
+        if (target !== root && !target.startsWith(`${root}${path.sep}`))
+            throw new Error(`The archive entry "${entry.name}" is outside of the target directory`);
+        switch (entry.type) {
+            case '5':
+                await mkdir(target, { recursive: true });
+                break;
+            case '0':
+            case '7': {
+                await mkdir(path.dirname(target), { recursive: true });
+                await writeFile(target, entry.data);
+                //The executable bits are kept (the scripts of the templates)
+                if (entry.mode & 0o111)
+                    await chmod(target, 0o755);
+                files.push(selected);
+                break;
+            }
+            case '2': {
+                const linked = path.resolve(path.dirname(target), entry.linkName);
+                if (!linked.startsWith(`${root}${path.sep}`))
+                    throw new Error(`The archive link "${entry.name}" points outside of the target directory`);
+                await mkdir(path.dirname(target), { recursive: true });
+                await symlink(entry.linkName, target);
+                break;
+            }
+            default:
+                //The hard links and the special files are not extracted
+                break;
+        }
+    }
+    return files;
+}
+/**
+ * Select the entries of an archive under a path, without it
+ * @param prefix the path ("package/template"), or the number of the leading elements removed
+ */
+export function under(prefix) {
+    if (typeof prefix === 'number')
+        return (name) => name.split('/').slice(prefix).join('/') || undefined;
+    const start = `${prefix.replace(/\/+$/, '')}/`;
+    return (name) => name.startsWith(start) ? name.slice(start.length) || undefined : undefined;
+}

package/dist/esm/lib/TemplateCatalog.js

@@ -0,0 +1,195 @@
+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;
+};
+import { existsSync } from 'node:fs';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { Component } from 'lakutata';
+import { Autoload, Singleton } from 'lakutata/decorator/di';
+import { Settings } from './Settings.js';
+import { warn } from './Output.js';
+import { cachedPackage, downloadPackage, majorManifest, resolvePackage } from './Registry.js';
+import { extractTarGz, under } from './Tar.js';
+import { toolMajor } from './Versions.js';
+import { readTemplateFeatures } from './TemplateFeatures.js';
+/**
+ * The package listing the official templates (its "lakutata.templates" field)
+ */
+const CATALOG_PACKAGE = '@lakutata/templates';
+/**
+ * The official templates known when the tool was released, when the catalog cannot be fetched
+ */
+export const BUILTIN_TEMPLATES = [
+    { name: 'default', description: 'A minimal application serving HTTP actions', package: '@lakutata/template-default', features: ['i18n'] },
+    { name: 'cli', description: 'A command line tool built into executables which run without Node.js', package: '@lakutata/template-cli', features: ['i18n', 'installer'] },
+    { name: 'service', description: 'An HTTP API deployed as a Docker image', package: '@lakutata/template-service', features: ['i18n', 'installer'] },
+    { name: 'web-react', description: 'An HTTP API serving a React single-page application (Vite)', package: '@lakutata/template-web-react', features: ['i18n', 'installer'] },
+    { name: 'web-next', description: 'An HTTP API serving a Next.js application from the same process', package: '@lakutata/template-web-next', features: ['i18n', 'installer'] },
+    { name: 'web-vue', description: 'An HTTP API serving a Vue single-page application (Vite)', package: '@lakutata/template-web-vue', features: ['i18n', 'installer'] },
+    { name: 'web-nuxt', description: 'An HTTP API serving a Nuxt application from the same process', package: '@lakutata/template-web-nuxt', features: ['i18n', 'installer'] },
+    { name: 'electron-react', description: 'A desktop application: Electron, its main process serving a React renderer over IPC', package: '@lakutata/template-electron-react', features: ['i18n'] },
+    { name: 'electron-vue', description: 'A desktop application: Electron, its main process serving a Vue renderer over IPC', package: '@lakutata/template-electron-vue', features: ['i18n'] }
+];
+/**
+ * How long the catalog is kept, 1 day
+ */
+const CACHE_TTL = 24 * 3600 * 1000;
+/**
+ * The project templates: the official ones are the packages "@lakutata/template-<name>" of the npm registry,
+ * the others npm packages, GitHub repositories or local directories
+ */
+let TemplateCatalog = class TemplateCatalog extends Component {
+    /**
+     * The file of the cache of the catalog
+     */
+    get cacheFile() {
+        return path.join(Settings.cacheDirectory, 'templates.json');
+    }
+    /**
+     * Read the cached catalog of the registry
+     */
+    async readCache() {
+        try {
+            const cache = JSON.parse(await readFile(this.cacheFile, 'utf8'));
+            return cache.registry === Settings.registry && Array.isArray(cache.templates) ? cache : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * The official templates: the catalog of the registry, cached for a day
+     * @param refresh fetch the catalog even when it is cached
+     */
+    async list(refresh = false) {
+        const cache = await this.readCache();
+        if (cache && !refresh && Date.now() - cache.updatedAt < CACHE_TTL)
+            return cache.templates;
+        //The catalog of the major version of the tool (its templates are the ones of this major version)
+        const templates = (await majorManifest(CATALOG_PACKAGE, toolMajor()))?.lakutata?.templates;
+        if (Array.isArray(templates)) {
+            await mkdir(path.dirname(this.cacheFile), { recursive: true });
+            await writeFile(this.cacheFile, JSON.stringify({ updatedAt: Date.now(), registry: Settings.registry, templates: templates }, null, 2));
+            return templates;
+        }
+        if (cache) {
+            warn(`The catalog of the templates cannot be fetched from ${Settings.registry}, the catalog of ${new Date(cache.updatedAt).toLocaleString()} is used`);
+            return cache.templates;
+        }
+        warn(`The catalog of the templates cannot be fetched from ${Settings.registry}, the templates known by the tool are listed`);
+        return BUILTIN_TEMPLATES;
+    }
+    /**
+     * Where a template comes from: "npm:<package>[@<version>]", "github:<owner>/<repo>[#<ref>]", a local directory,
+     * or the name of an official template
+     * @param template
+     */
+    async resolve(template) {
+        if (template.startsWith('npm:')) {
+            const matched = /^((?:@[^/@]+\/)?[^/@]+)(?:@(.+))?$/.exec(template.slice(4));
+            if (!matched)
+                throw new Error(`Invalid npm template "${template}": npm:<package>[@<version>]`);
+            return { kind: 'npm', package: matched[1], version: matched[2], official: false };
+        }
+        if (template.startsWith('github:')) {
+            const matched = /^([^/#]+\/[^/#]+)(?:#(.+))?$/.exec(template.slice(7));
+            if (!matched)
+                throw new Error(`Invalid GitHub template "${template}": github:<owner>/<repo>[#<ref>]`);
+            return { kind: 'github', repository: matched[1], ref: matched[2] };
+        }
+        if (/^[./~]/.test(template) || path.isAbsolute(template) || existsSync(template)) {
+            const directory = path.resolve(template.replace(/^~(?=$|\/)/, os.homedir()));
+            if (!existsSync(directory))
+                throw new Error(`The template directory ${directory} does not exist`);
+            return { kind: 'local', directory: directory };
+        }
+        const official = (await this.list()).find((info) => info.name === template);
+        return { kind: 'npm', package: official?.package ?? `@lakutata/template-${template}`, official: true };
+    }
+    /**
+     * The package of a template, the cached one when the registry cannot be reached
+     * @param source
+     * @param work
+     */
+    async preparePackage(source, work) {
+        //An official template has the major version of the tool
+        const wanted = source.version ?? (source.official ? toolMajor() : undefined);
+        let pkg;
+        try {
+            pkg = await resolvePackage(source.package, wanted);
+        }
+        catch (error) {
+            const cached = typeof wanted === 'string' ? undefined : await cachedPackage(source.package, wanted);
+            if (!cached)
+                throw error;
+            warn(`${error.message}, the cached ${source.package}@${cached.version} is used`);
+            await extractTarGz(cached.archive, work, under('package'));
+            return `${source.package}@${cached.version}`;
+        }
+        if (!pkg) {
+            const names = source.official ? `, the templates are: ${(await this.list()).map((info) => info.name).join(', ')}` : '';
+            throw new Error(`The template ${source.official ? `"${source.package.replace('@lakutata/template-', '')}" ` : ''}does not exist (${source.package} is not on ${Settings.registry})${names}`);
+        }
+        const archive = await downloadPackage(pkg);
+        const version = pkg.version;
+        await extractTarGz(archive, work, under('package'));
+        return `${source.package}@${version}`;
+    }
+    /**
+     * A template ready: a template package has its files in template/ and the ones of its features in features/ (its
+     * package.json declaring them), the other sources are the template
+     * @param directory
+     * @param label
+     * @param cleanup
+     */
+    async prepared(directory, label, cleanup) {
+        const packaged = existsSync(path.join(directory, 'template'));
+        return {
+            label: label,
+            root: packaged ? path.join(directory, 'template') : directory,
+            features: packaged ? await readTemplateFeatures(directory) : {},
+            featuresDirectory: path.join(directory, 'features'),
+            cleanup: cleanup
+        };
+    }
+    /**
+     * Get the files of a template
+     * @param source
+     */
+    async prepare(source) {
+        if (source.kind === 'local') {
+            return await this.prepared(source.directory, source.directory, async () => undefined);
+        }
+        const work = await mkdtemp(path.join(os.tmpdir(), 'lakutata-template-'));
+        const cleanup = async () => rm(work, { recursive: true, force: true });
+        try {
+            let label;
+            if (source.kind === 'npm') {
+                label = await this.preparePackage(source, work);
+            }
+            else {
+                const url = `${Settings.githubDownload}/${source.repository}/archive/${source.ref ?? 'HEAD'}.tar.gz`;
+                const response = await fetch(url, { headers: { 'User-Agent': 'lakutata-cli' }, signal: AbortSignal.timeout(60000) });
+                if (!response.ok)
+                    throw new Error(`The template ${source.repository} cannot be downloaded from ${url}: ${response.status} ${response.statusText}`);
+                //The archives of GitHub have a root directory
+                await extractTarGz(Buffer.from(await response.arrayBuffer()), work, under(1));
+                label = `github:${source.repository}${source.ref ? `#${source.ref}` : ''}`;
+            }
+            return await this.prepared(work, label, cleanup);
+        }
+        catch (error) {
+            await cleanup();
+            throw error;
+        }
+    }
+};
+TemplateCatalog = __decorate([
+    Autoload(),
+    Singleton()
+], TemplateCatalog);
+export { TemplateCatalog };

package/dist/esm/lib/TemplateFeatures.js

@@ -0,0 +1,141 @@
+import { existsSync } from 'node:fs';
+import { copyFile, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * The files the npm packages cannot hold under their name, kept as "_<name>" in the templates
+ */
+export const DOTFILES = ['gitignore', 'npmrc', 'npmignore', 'gitattributes', 'editorconfig', 'dockerignore', 'nvmrc', 'env', 'eslintrc.json', 'prettierrc'];
+/**
+ * The path of a file of a template in the project: "_gitignore" becomes ".gitignore"
+ * @param file relative to the template
+ */
+export function projectPath(file) {
+    const name = path.basename(file);
+    return name.startsWith('_') && DOTFILES.includes(name.slice(1)) ? path.join(path.dirname(file), `.${name.slice(1)}`) : file;
+}
+/**
+ * The optional features of a template, declared by its package (its "lakutata.features" field: their names and their
+ * descriptions), their files in its features/<name> directory
+ * @param packageRoot the directory of the package of the template
+ */
+export async function readTemplateFeatures(packageRoot) {
+    const manifest = path.join(packageRoot, 'package.json');
+    if (!existsSync(manifest))
+        return {};
+    const features = JSON.parse(await readFile(manifest, 'utf8'))?.lakutata?.features;
+    if (features === undefined)
+        return {};
+    if (features === null || typeof features !== 'object' || Array.isArray(features) ||
+        Object.entries(features).some(([name, description]) => !/^[a-z][a-z0-9-]*$/.test(name) || typeof description !== 'string')) {
+        throw new Error(`The features of the template (${manifest}, lakutata.features) must be their names (lower case) and their descriptions`);
+    }
+    return features;
+}
+/**
+ * Whether a value is a plain object (of JSON)
+ * @param value
+ */
+function isObjectValue(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Merge a JSON value into another one: the objects merged by their keys, the other values replaced
+ * @param target
+ * @param source
+ */
+export function mergeJson(target, source) {
+    if (!isObjectValue(target) || !isObjectValue(source))
+        return source;
+    const merged = { ...target };
+    for (const [key, value] of Object.entries(source))
+        merged[key] = key in target ? mergeJson(target[key], value) : value;
+    return merged;
+}
+/**
+ * The files of a directory, relative to it
+ * @param directory
+ * @param base
+ */
+async function listFiles(directory, base = directory) {
+    const files = [];
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+        const file = path.join(directory, entry.name);
+        if (entry.isDirectory())
+            files.push(...await listFiles(file, base));
+        else
+            files.push(path.relative(base, file));
+    }
+    return files;
+}
+/**
+ * Add the files of a feature to a project: the new files copied, the JSON files the project has merged into its ones
+ * (the scripts of package.json, the options of tsconfig.json)
+ * @param featureDirectory
+ * @param project
+ * @return the files added to the project, relative to it
+ */
+export async function applyFeatureFiles(featureDirectory, project) {
+    const added = [];
+    for (const file of await listFiles(featureDirectory)) {
+        const relative = projectPath(file);
+        const target = path.join(project, relative);
+        await mkdir(path.dirname(target), { recursive: true });
+        if (existsSync(target) && file.endsWith('.json')) {
+            const merged = mergeJson(JSON.parse(await readFile(target, 'utf8')), JSON.parse(await readFile(path.join(featureDirectory, file), 'utf8')));
+            await writeFile(target, `${JSON.stringify(merged, null, 2)}\n`);
+            continue;
+        }
+        await copyFile(path.join(featureDirectory, file), target);
+        added.push(relative);
+    }
+    return added;
+}
+/**
+ * A line marking a block of a feature: "//@if <feature>", "//@if !<feature>", "//@else", "//@end", in the comments of
+ * the languages (//, #, <!-- -->, /* * /)
+ */
+const MARKER = /^\s*(?:\/\/|#|<!--|\/\*)\s*@(if|else|end)\b\s*(!?[a-z][a-z0-9-]*)?\s*(?:-->|\*\/)?\s*$/;
+/**
+ * The text of a file of a template with the blocks of the features: the blocks of the features enabled kept, the
+ * others removed, the markers removed
+ * @param text
+ * @param enabled the features enabled
+ * @param file the file, for the errors
+ */
+export function applyFeatureBlocks(text, enabled, file) {
+    if (!/@(?:if|else|end)\b/.test(text))
+        return text;
+    const lines = text.split('\n');
+    const kept = [];
+    //The blocks the line is in: whether their branch is kept
+    const blocks = [];
+    for (const [index, line] of lines.entries()) {
+        const marker = MARKER.exec(line);
+        if (!marker) {
+            if (blocks.every((block) => block.keep))
+                kept.push(line);
+            continue;
+        }
+        const [, directive, condition] = marker;
+        if (directive === 'if') {
+            if (!condition)
+                throw new Error(`${file}:${index + 1}: @if needs a feature`);
+            const negated = condition.startsWith('!');
+            blocks.push({ keep: enabled.has(condition.replace(/^!/, '')) !== negated, line: index + 1, elsed: false });
+        }
+        else if (directive === 'else') {
+            const block = blocks.at(-1);
+            if (!block || block.elsed)
+                throw new Error(`${file}:${index + 1}: @else without its @if`);
+            block.keep = !block.keep;
+            block.elsed = true;
+        }
+        else {
+            if (!blocks.pop())
+                throw new Error(`${file}:${index + 1}: @end without its @if`);
+        }
+    }
+    if (blocks.length)
+        throw new Error(`${file}:${blocks.at(-1).line}: @if without its @end`);
+    return kept.join('\n');
+}

package/dist/esm/lib/Versions.js

@@ -0,0 +1,58 @@
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { latestManifest } from './Registry.js';
+const require = createRequire(import.meta.url);
+/**
+ * The package.json of the tool
+ */
+export function toolPackage() {
+    return require('../../../package.json');
+}
+/**
+ * The version of the framework used by the tool
+ */
+export function frameworkVersion() {
+    return require('lakutata/package.json').version;
+}
+/**
+ * The latest version of a package on the registry, undefined when it cannot be fetched
+ * @param name
+ */
+export async function latestVersion(name) {
+    return (await latestManifest(name))?.version;
+}
+/**
+ * The major version of the tool: the templates of the same major version are used
+ */
+export function toolMajor() {
+    return Number(toolPackage().version.split('.')[0]);
+}
+/**
+ * The version of the framework of the project of a directory (its dependency, and the installed one)
+ * @param directory
+ */
+export async function projectFrameworkVersion(directory) {
+    for (let current = path.resolve(directory);; current = path.dirname(current)) {
+        try {
+            const pkg = JSON.parse(await readFile(path.join(current, 'package.json'), 'utf8'));
+            const declared = pkg.dependencies?.lakutata ?? pkg.devDependencies?.lakutata;
+            if (!declared)
+                return undefined;
+            let installed;
+            try {
+                installed = createRequire(path.join(current, 'package.json'))('lakutata/package.json').version;
+            }
+            catch {
+                installed = undefined;
+            }
+            return { project: pkg.name ?? path.basename(current), declared: declared, installed: installed };
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                return undefined;
+        }
+        if (path.dirname(current) === current)
+            return undefined;
+    }
+}