@trinacria/cli 0.1.1-alpha.1

package/README.md

@@ -0,0 +1,109 @@
+# @trinacria/cli
+
+`@trinacria/cli` is the command-line tool for Trinacria apps.
+
+It provides:
+
+- app scaffolding (`new`, `create`, `init`)
+- development mode with watch/restart (`dev`)
+- TypeScript build (`build`)
+- production start from compiled output (`start`)
+
+## Install
+
+Use it without global install:
+
+```bash
+npx @trinacria/cli@alpha --help
+```
+
+Or install in your project:
+
+```bash
+npm i -D @trinacria/cli
+```
+
+## Create a new app
+
+```bash
+npx @trinacria/cli@alpha new my-app
+cd my-app
+npm install
+npm run dev
+```
+
+Quick start with explicit templates:
+
+```bash
+npx @trinacria/cli@alpha new my-app --template app-starter
+npx @trinacria/cli@alpha new my-cron --template cron-example
+npx @trinacria/cli@alpha new my-api-pg --template api-prisma-postgresql
+npx @trinacria/cli@alpha new my-api-mongo --template api-mongoose-mongodb
+npx @trinacria/cli@alpha new my-api-redis --template api-events-redis
+npx @trinacria/cli@alpha new my-api-rabbit --template api-events-rabbitmq
+```
+
+Aliases:
+
+```bash
+npx @trinacria/cli@alpha create my-app
+npx @trinacria/cli@alpha init my-app
+```
+
+## Available templates
+
+- `app-starter` (aliases: `minimal`, `starter`, `base`, `default`)
+- `cron-example`
+- `api-prisma-postgresql`
+- `api-mongoose-mongodb`
+- `api-events-redis`
+- `api-events-rabbitmq`
+
+Example:
+
+```bash
+npx @trinacria/cli@alpha new my-app --template minimal
+```
+
+## Commands
+
+```bash
+trinacria new <project-name> [--template <name>] [--no-install] [--no-git] [--force]
+trinacria dev
+trinacria build
+trinacria start
+```
+
+## Config file
+
+Supported config names in your app root:
+
+- `trinacria.config.js`
+- `trinacria.config.cjs`
+- `trinacria.config.mjs`
+
+Example:
+
+```js
+/** @type {import('@trinacria/cli').TrinacriaConfig} */
+export default {
+  entry: "src/main.ts",
+  outDir: "dist",
+  watchDir: "src",
+  env: "development",
+};
+```
+
+## Notes
+
+- In generated apps, `@trinacria/cli` is added to `devDependencies`.
+- Generated app includes `.env` created from `.env.example` (if present).
+- Generated app keeps `.gitignore` (and writes a default one if missing).
+- `@trinacria/*` dependencies are pinned to the same version as the CLI release used for scaffolding.
+- `dev` uses watch mode with automatic restart on source changes.
+- `start` runs the compiled file mapped from your configured entry.
+
+## Links
+
+- Repository: [https://github.com/tascaenzo/trinacria](https://github.com/tascaenzo/trinacria)
+- Documentation: see `docs/en` and `docs/it` in the repository.

package/README.npm.md

@@ -0,0 +1,109 @@
+# @trinacria/cli
+
+`@trinacria/cli` is the command-line tool for Trinacria apps.
+
+It provides:
+
+- app scaffolding (`new`, `create`, `init`)
+- development mode with watch/restart (`dev`)
+- TypeScript build (`build`)
+- production start from compiled output (`start`)
+
+## Install
+
+Use it without global install:
+
+```bash
+npx @trinacria/cli@alpha --help
+```
+
+Or install in your project:
+
+```bash
+npm i -D @trinacria/cli
+```
+
+## Create a new app
+
+```bash
+npx @trinacria/cli@alpha new my-app
+cd my-app
+npm install
+npm run dev
+```
+
+Quick start with explicit templates:
+
+```bash
+npx @trinacria/cli@alpha new my-app --template app-starter
+npx @trinacria/cli@alpha new my-cron --template cron-example
+npx @trinacria/cli@alpha new my-api-pg --template api-prisma-postgresql
+npx @trinacria/cli@alpha new my-api-mongo --template api-mongoose-mongodb
+npx @trinacria/cli@alpha new my-api-redis --template api-events-redis
+npx @trinacria/cli@alpha new my-api-rabbit --template api-events-rabbitmq
+```
+
+Aliases:
+
+```bash
+npx @trinacria/cli@alpha create my-app
+npx @trinacria/cli@alpha init my-app
+```
+
+## Available templates
+
+- `app-starter` (aliases: `minimal`, `starter`, `base`, `default`)
+- `cron-example`
+- `api-prisma-postgresql`
+- `api-mongoose-mongodb`
+- `api-events-redis`
+- `api-events-rabbitmq`
+
+Example:
+
+```bash
+npx @trinacria/cli@alpha new my-app --template minimal
+```
+
+## Commands
+
+```bash
+trinacria new <project-name> [--template <name>] [--no-install] [--no-git] [--force]
+trinacria dev
+trinacria build
+trinacria start
+```
+
+## Config file
+
+Supported config names in your app root:
+
+- `trinacria.config.js`
+- `trinacria.config.cjs`
+- `trinacria.config.mjs`
+
+Example:
+
+```js
+/** @type {import('@trinacria/cli').TrinacriaConfig} */
+export default {
+  entry: "src/main.ts",
+  outDir: "dist",
+  watchDir: "src",
+  env: "development",
+};
+```
+
+## Notes
+
+- In generated apps, `@trinacria/cli` is added to `devDependencies`.
+- Generated app includes `.env` created from `.env.example` (if present).
+- Generated app keeps `.gitignore` (and writes a default one if missing).
+- `@trinacria/*` dependencies are pinned to the same version as the CLI release used for scaffolding.
+- `dev` uses watch mode with automatic restart on source changes.
+- `start` runs the compiled file mapped from your configured entry.
+
+## Links
+
+- Repository: [https://github.com/tascaenzo/trinacria](https://github.com/tascaenzo/trinacria)
+- Documentation: see `docs/en` and `docs/it` in the repository.

package/dist/cli.d.ts

@@ -0,0 +1,19 @@
+import { dev } from "./commands/dev";
+import { build } from "./commands/build";
+import { start } from "./commands/start";
+import { createNewApp } from "./commands/new";
+import { loadConfig } from "./config/load-config";
+export declare function printHelp(): void;
+interface CliDeps {
+    loadConfig: typeof loadConfig;
+    dev: typeof dev;
+    build: typeof build;
+    start: typeof start;
+    createNewApp: typeof createNewApp;
+    printHelp: () => void;
+    exit: (code: number) => void;
+    logError: (message: string, error?: unknown) => void;
+}
+export declare function runCli(args: string[], deps?: CliDeps): Promise<void>;
+export declare function main(): Promise<void>;
+export {};

package/dist/cli.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printHelp = printHelp;
+exports.runCli = runCli;
+exports.main = main;
+const dev_1 = require("./commands/dev");
+const build_1 = require("./commands/build");
+const start_1 = require("./commands/start");
+const new_1 = require("./commands/new");
+const load_config_1 = require("./config/load-config");
+const core_1 = require("@trinacria/core");
+const context = "TrinacriaCLI";
+const log = new core_1.ConsoleLogger(context);
+function printHelp() {
+    console.log(`
+Trinacria CLI
+
+Usage:
+  trinacria new <project-name> [--template <name>] [--no-install] [--no-git] [--force]
+  trinacria create <project-name> [--template <name>] [--no-install] [--no-git] [--force]
+  trinacria init <project-name> [--template <name>] [--no-install] [--no-git] [--force]
+  trinacria dev
+  trinacria build
+  trinacria start
+
+Options:
+  --config <path>   Specify custom config file
+  --help            Show help
+
+Notes:
+  - default template is "app-starter" (alias: minimal, starter, base, default)
+`);
+}
+const defaultDeps = {
+    loadConfig: load_config_1.loadConfig,
+    dev: dev_1.dev,
+    build: build_1.build,
+    start: start_1.start,
+    createNewApp: new_1.createNewApp,
+    printHelp,
+    exit: (code) => process.exit(code),
+    logError: (message, error) => log.error(message, error, context),
+};
+async function runCli(args, deps = defaultDeps) {
+    const command = args[0];
+    if (!command || command === "--help") {
+        deps.printHelp();
+        deps.exit(0);
+        return;
+    }
+    try {
+        switch (command) {
+            case "new":
+            case "create":
+            case "init":
+                await deps.createNewApp(args.slice(1));
+                break;
+            case "dev":
+            case "build":
+            case "start": {
+                const config = await deps.loadConfig(args);
+                if (command === "dev") {
+                    await deps.dev(config);
+                }
+                else if (command === "build") {
+                    await deps.build(config);
+                }
+                else {
+                    await deps.start(config);
+                }
+                break;
+            }
+            default:
+                deps.logError(`Unknown command: ${command}`);
+                deps.printHelp();
+                deps.exit(1);
+                return;
+        }
+    }
+    catch (err) {
+        deps.logError("CLI execution failed", err);
+        deps.exit(1);
+        return;
+    }
+}
+async function main() {
+    await runCli(process.argv.slice(2));
+}

package/dist/commands/build.d.ts

@@ -0,0 +1,2 @@
+import { ResolvedConfig } from "../config/config.contract";
+export declare function build(config: ResolvedConfig): Promise<void>;

package/dist/commands/build.js

@@ -0,0 +1,102 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.build = build;
+const typescript_1 = __importDefault(require("typescript"));
+const node_perf_hooks_1 = require("node:perf_hooks");
+const color = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    red: "\x1b[31m",
+    yellow: "\x1b[33m",
+    green: "\x1b[32m",
+    cyan: "\x1b[36m",
+};
+function title(msg) {
+    console.log(`${color.cyan}${color.bold}TRINACRIA${color.reset} ${msg}`);
+}
+function success(msg) {
+    console.log(`${color.green}✔ ${msg}${color.reset}`);
+}
+function error(msg) {
+    console.error(`${color.red}✖ ${msg}${color.reset}`);
+}
+function warning(msg) {
+    console.warn(`${color.yellow}⚠ ${msg}${color.reset}`);
+}
+async function build(config) {
+    title("Building application...\n");
+    const startTime = node_perf_hooks_1.performance.now();
+    const configPath = typescript_1.default.findConfigFile(process.cwd(), typescript_1.default.sys.fileExists, "tsconfig.json");
+    if (!configPath) {
+        error("Could not find tsconfig.json");
+        process.exit(1);
+    }
+    const configFile = typescript_1.default.readConfigFile(configPath, typescript_1.default.sys.readFile);
+    if (configFile.error) {
+        const message = typescript_1.default.formatDiagnosticsWithColorAndContext([configFile.error], formatHost());
+        error(message);
+        process.exit(1);
+    }
+    const parsed = typescript_1.default.parseJsonConfigFileContent(configFile.config, typescript_1.default.sys, process.cwd(), {
+        outDir: config.outDir,
+    });
+    const program = typescript_1.default.createProgram(parsed.fileNames, parsed.options);
+    // 📦 Mostra file compilati (non declaration)
+    const sourceFiles = program
+        .getSourceFiles()
+        .filter((f) => !f.isDeclarationFile);
+    console.log(`${color.dim}Compiling ${sourceFiles.length} files...${color.reset}\n`);
+    const emitResult = program.emit();
+    const diagnostics = typescript_1.default
+        .getConfigFileParsingDiagnostics(parsed)
+        .concat(typescript_1.default.getPreEmitDiagnostics(program), emitResult.diagnostics);
+    let errorCount = 0;
+    let warningCount = 0;
+    diagnostics.forEach((diagnostic) => {
+        const message = typescript_1.default.flattenDiagnosticMessageText(diagnostic.messageText, "\n");
+        if (diagnostic.category === typescript_1.default.DiagnosticCategory.Error) {
+            errorCount++;
+        }
+        else if (diagnostic.category === typescript_1.default.DiagnosticCategory.Warning) {
+            warningCount++;
+        }
+        if (diagnostic.file && diagnostic.start !== undefined) {
+            const { line, character } = diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start);
+            const location = `${diagnostic.file.fileName}:${line + 1}:${character + 1}`;
+            if (diagnostic.category === typescript_1.default.DiagnosticCategory.Error) {
+                error(`${location} - ${message}`);
+            }
+            else {
+                warning(`${location} - ${message}`);
+            }
+        }
+        else {
+            if (diagnostic.category === typescript_1.default.DiagnosticCategory.Error) {
+                error(message);
+            }
+            else {
+                warning(message);
+            }
+        }
+    });
+    const duration = (node_perf_hooks_1.performance.now() - startTime).toFixed(2);
+    console.log(""); // spacing
+    if (emitResult.emitSkipped || errorCount > 0) {
+        error(`Build failed with ${errorCount} error(s) and ${warningCount} warning(s)`);
+        process.exit(1);
+    }
+    success(`Build completed in ${duration}ms`);
+    console.log(`${color.dim}Output directory:${color.reset} ${config.outDir}`);
+    console.log(`${color.dim}Files compiled:${color.reset} ${sourceFiles.length}\n`);
+}
+function formatHost() {
+    return {
+        getCanonicalFileName: (fileName) => fileName,
+        getCurrentDirectory: () => process.cwd(),
+        getNewLine: () => "\n",
+    };
+}

package/dist/commands/dev.d.ts

@@ -0,0 +1,28 @@
+import { ChildProcess } from "node:child_process";
+import { ResolvedConfig } from "../config/config.contract";
+interface DevDeps {
+    watch: (watchDir: string) => {
+        on(event: "all", listener: () => void): void;
+        close(): Promise<void>;
+    };
+    startApp: (entry: string) => ChildProcess;
+    stopChild: (child: ChildProcess) => Promise<void>;
+    setTimeoutFn: typeof setTimeout;
+    clearTimeoutFn: typeof clearTimeout;
+    now: () => number;
+    onSignal: (signal: NodeJS.Signals, handler: () => void) => void;
+    exit: (code: number) => void;
+    info: (message: string) => void;
+    error: (message: string) => void;
+}
+export declare function runDev(config: ResolvedConfig, deps?: DevDeps): Promise<void>;
+export declare function dev(config: ResolvedConfig): Promise<void>;
+declare function resolveTsxCliPath(): string;
+declare function resetTsxCliEntryCacheForTests(): void;
+declare function stopChild(child: ChildProcess): Promise<void>;
+export declare const __devTestUtils: {
+    resolveTsxCliPath: typeof resolveTsxCliPath;
+    stopChild: typeof stopChild;
+    resetTsxCliEntryCacheForTests: typeof resetTsxCliEntryCacheForTests;
+};
+export {};

package/dist/commands/dev.js

@@ -0,0 +1,186 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__devTestUtils = void 0;
+exports.runDev = runDev;
+exports.dev = dev;
+const node_child_process_1 = require("node:child_process");
+const chokidar_1 = __importDefault(require("chokidar"));
+const node_path_1 = __importDefault(require("node:path"));
+const core_1 = require("@trinacria/core");
+const context = "TrinacriaCLI";
+const log = new core_1.ConsoleLogger(context);
+const RESTART_DEBOUNCE_MS = 100;
+const STOP_TIMEOUT_MS = 3000;
+const NON_RESTARTABLE_EXIT_CODES = new Set([78]);
+let tsxCliEntryCache = null;
+const defaultDevDeps = {
+    watch: (watchDir) => chokidar_1.default.watch(watchDir, {
+        ignoreInitial: true,
+    }),
+    startApp,
+    stopChild,
+    setTimeoutFn: setTimeout,
+    clearTimeoutFn: clearTimeout,
+    now: () => Date.now(),
+    onSignal: (signal, handler) => {
+        process.once(signal, handler);
+    },
+    exit: (code) => {
+        process.exit(code);
+    },
+    info: (message) => {
+        log.info(message, context);
+    },
+    error: (message) => {
+        log.error(message, context);
+    },
+};
+async function runDev(config, deps = defaultDevDeps) {
+    const entry = node_path_1.default.resolve(config.entry);
+    const crashLoopWindowMs = config.crashLoopWindowMs;
+    const maxConsecutiveCrashRestarts = config.maxConsecutiveCrashRestarts;
+    deps.info("Starting in dev mode");
+    const watcher = deps.watch(config.watchDir);
+    let restarting = false;
+    let pendingRestart = false;
+    let stopping = false;
+    let crashCount = 0;
+    let crashWindowStartedAt = 0;
+    let restartTimeout = null;
+    const handleChildExit = (code) => {
+        if (stopping || restarting) {
+            return;
+        }
+        if (code !== 0) {
+            if (code !== null && NON_RESTARTABLE_EXIT_CODES.has(code)) {
+                deps.error(`Application stopped with non-restartable exit code ${code}. Waiting for source changes...`);
+                return;
+            }
+            if (isCrashLoop()) {
+                deps.error(`Application crashed ${maxConsecutiveCrashRestarts} times in ${Math.floor(crashLoopWindowMs / 1000)}s. Waiting for source changes...`);
+                return;
+            }
+            scheduleRestart(`App crashed (code ${code})`);
+        }
+    };
+    const createTrackedChild = () => {
+        const next = deps.startApp(entry);
+        next.on("exit", handleChildExit);
+        next.on("error", (err) => {
+            if (!stopping) {
+                scheduleRestart(`App process failed to start: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        });
+        return next;
+    };
+    let child = createTrackedChild();
+    const scheduleRestart = (reason) => {
+        if (restartTimeout) {
+            deps.clearTimeoutFn(restartTimeout);
+        }
+        restartTimeout = deps.setTimeoutFn(() => {
+            void restart(reason);
+        }, RESTART_DEBOUNCE_MS);
+    };
+    const restart = async (reason) => {
+        if (stopping)
+            return;
+        if (restarting) {
+            pendingRestart = true;
+            return;
+        }
+        restarting = true;
+        try {
+            do {
+                pendingRestart = false;
+                deps.info(`${reason} — restarting application`);
+                await deps.stopChild(child);
+                child = createTrackedChild();
+            } while (pendingRestart);
+        }
+        finally {
+            restarting = false;
+        }
+    };
+    watcher.on("all", () => {
+        crashCount = 0;
+        crashWindowStartedAt = 0;
+        scheduleRestart("Source changed");
+    });
+    const cleanup = async (signal) => {
+        stopping = true;
+        if (restartTimeout) {
+            deps.clearTimeoutFn(restartTimeout);
+            restartTimeout = null;
+        }
+        await watcher.close();
+        await deps.stopChild(child);
+        deps.exit(signal === "SIGINT" ? 130 : 143);
+    };
+    deps.onSignal("SIGINT", () => {
+        void cleanup("SIGINT");
+    });
+    deps.onSignal("SIGTERM", () => {
+        void cleanup("SIGTERM");
+    });
+    function isCrashLoop() {
+        const now = deps.now();
+        if (crashWindowStartedAt === 0 ||
+            now - crashWindowStartedAt > crashLoopWindowMs) {
+            crashWindowStartedAt = now;
+            crashCount = 1;
+            return false;
+        }
+        crashCount += 1;
+        return crashCount >= maxConsecutiveCrashRestarts;
+    }
+}
+async function dev(config) {
+    await runDev(config);
+}
+function startApp(entry) {
+    return (0, node_child_process_1.spawn)(process.execPath, [resolveTsxCliPath(), entry], {
+        stdio: "inherit",
+    });
+}
+function resolveTsxCliPath() {
+    if (tsxCliEntryCache) {
+        return tsxCliEntryCache;
+    }
+    try {
+        tsxCliEntryCache = require.resolve("tsx/cli");
+        return tsxCliEntryCache;
+    }
+    catch (error) {
+        throw new Error(`Unable to resolve tsx CLI entry. Ensure \"tsx\" is installed. ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function resetTsxCliEntryCacheForTests() {
+    tsxCliEntryCache = null;
+}
+function stopChild(child) {
+    if (child.exitCode !== null || child.signalCode !== null) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        const forceKillTimer = setTimeout(() => {
+            if (child.exitCode === null && child.signalCode === null) {
+                child.kill("SIGKILL");
+            }
+        }, STOP_TIMEOUT_MS);
+        forceKillTimer.unref();
+        child.once("exit", () => {
+            clearTimeout(forceKillTimer);
+            resolve();
+        });
+        child.kill("SIGTERM");
+    });
+}
+exports.__devTestUtils = {
+    resolveTsxCliPath,
+    stopChild,
+    resetTsxCliEntryCacheForTests,
+};

package/dist/commands/new.d.ts

@@ -0,0 +1,41 @@
+import fs from "node:fs";
+declare const TEMPLATE_APP_NAMES: readonly ["app-starter", "cron-example", "api-prisma-postgresql", "api-mongoose-mongodb", "api-events-redis", "api-events-rabbitmq"];
+type TemplateAppName = (typeof TEMPLATE_APP_NAMES)[number];
+interface NewOptions {
+    projectName: string;
+    template: TemplateAppName;
+    install: boolean;
+    git: boolean;
+    force: boolean;
+}
+interface NewDeps {
+    cwd: () => string;
+    templatesRoot: () => string;
+    pathExists: (target: string) => boolean;
+    mkdir: (target: string) => void;
+    readdir: (target: string) => fs.Dirent[];
+    stat: (target: string) => fs.Stats;
+    readFile: (target: string) => string;
+    writeFile: (target: string, content: string) => void;
+    copyFile: (from: string, to: string) => void;
+    runCommand: (command: string, args: string[], cwd: string) => Promise<void>;
+    info: (message: string) => void;
+}
+export declare function createNewApp(args: string[], deps?: NewDeps): Promise<void>;
+declare function parseNewArgs(args: string[]): NewOptions;
+declare function normalizeTemplateName(templateInput: string): TemplateAppName;
+declare function ensureTargetDirectory(targetDir: string, force: boolean, deps: NewDeps): void;
+declare function ensureGeneratedProjectFiles(targetDir: string, deps: NewDeps): void;
+declare function adaptGeneratedPackageJson(targetDir: string, projectName: string, trinacriaVersion: string, deps: NewDeps): void;
+declare function normalizeScripts(scriptsInput: Record<string, unknown> | undefined): Record<string, string>;
+declare function normalizeDependencyMap(input: Record<string, unknown> | undefined, trinacriaVersion: string): Record<string, string>;
+export declare const __newTestUtils: {
+    parseNewArgs: typeof parseNewArgs;
+    normalizeTemplateName: typeof normalizeTemplateName;
+    normalizeDependencyMap: typeof normalizeDependencyMap;
+    normalizeScripts: typeof normalizeScripts;
+    adaptGeneratedPackageJson: typeof adaptGeneratedPackageJson;
+    ensureGeneratedProjectFiles: typeof ensureGeneratedProjectFiles;
+    ensureTargetDirectory: typeof ensureTargetDirectory;
+};
+export {};