@expressots/cli 4.0.0-preview.2 → 4.0.0-preview.3

package/bin/cicd/cli.d.ts

@@ -1,5 +1,5 @@
 import { CommandModule } from "yargs";
-type CommandModuleArgs = {};
+type CommandModuleArgs = Record<string, never>;
 export type CIPlatform = "github" | "gitlab" | "circleci" | "jenkins" | "bitbucket" | "azure";
 export type CIStrategy = "basic" | "comprehensive" | "security-focused";
 declare const cicdCommand: () => CommandModule<CommandModuleArgs, any>;

package/bin/cicd/cli.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.cicdCommand = void 0;
 const form_1 = require("./form");
+const cli_ui_1 = require("../utils/cli-ui");
 const cicdCommand = () => {
     return {
         command: "cicd <action> [platform]",
@@ -118,7 +119,8 @@ const cicdCommand = () => {
                     await (0, form_1.validatePipelines)();
                     break;
                 default:
-                    console.log(`Unknown action: ${action}`);
+                    (0, cli_ui_1.printError)(`Unknown action: ${action}`, "cicd");
+                    process.exit(1);
             }
         },
     };

package/bin/cicd/form.js

@@ -10,6 +10,7 @@ const chalk_1 = __importDefault(require("chalk"));
 const inquirer_1 = __importDefault(require("inquirer"));
 const project_analyzer_1 = require("../containerize/analyzers/project-analyzer");
 const generators_1 = require("./generators");
+const cli_ui_1 = require("../utils/cli-ui");
 const PLATFORMS = [
     {
         id: "github",
@@ -46,7 +47,7 @@ const PLATFORMS = [
  * Interactive CI/CD setup wizard
  */
 async function initCICD(options) {
-    console.log(chalk_1.default.cyan("\n🔧 ExpressoTS CI/CD Setup Wizard\n"));
+    (0, cli_ui_1.printSection)("🔧 ExpressoTS CI/CD Setup Wizard");
     // Analyze project first
     const analysis = await (0, project_analyzer_1.analyzeProject)();
     // Interactive prompts
@@ -148,7 +149,7 @@ exports.initCICD = initCICD;
  * Generate CI/CD configuration for specific platform(s)
  */
 async function generateCICD(options) {
-    console.log(chalk_1.default.cyan("\n🔧 ExpressoTS CI/CD Generator\n"));
+    (0, cli_ui_1.printSection)("🔧 ExpressoTS CI/CD Generator");
     if (!options.platform) {
         console.log(chalk_1.default.red("Error: Please specify a platform. Use 'expressots cicd list' to see available platforms."));
         return;
@@ -173,7 +174,7 @@ exports.generateCICD = generateCICD;
  * List available CI/CD platforms
  */
 async function listPlatforms() {
-    console.log(chalk_1.default.cyan("\n📋 Available CI/CD Platforms\n"));
+    (0, cli_ui_1.printSection)("📋 Available CI/CD Platforms");
     console.log(chalk_1.default.bold("Platform".padEnd(20) + "Description".padEnd(45) + "Status"));
     console.log("-".repeat(80));
     for (const platform of PLATFORMS) {
@@ -191,7 +192,7 @@ exports.listPlatforms = listPlatforms;
  * Validate existing CI/CD configurations
  */
 async function validatePipelines() {
-    console.log(chalk_1.default.cyan("\n🔍 Validating CI/CD Configurations\n"));
+    (0, cli_ui_1.printSection)("🔍 Validating CI/CD Configurations");
     const cwd = process.cwd();
     const validations = [];
     // Check for each platform's config file

package/bin/cli.d.ts

@@ -1,6 +1,2 @@
 #!/usr/bin/env node
-/**
- * The current version of the ExpressoTS Bundle.
- * core, adapters, and cli.
- */
-export declare const BUNDLE_VERSION = "4.0.0-preview.2";
+export declare const BUNDLE_VERSION: string;

package/bin/cli.js

@@ -5,6 +5,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BUNDLE_VERSION = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
 const chalk_1 = __importDefault(require("chalk"));
 const yargs_1 = __importDefault(require("yargs"));
 const helpers_1 = require("yargs/helpers");
@@ -23,14 +25,60 @@ const new_1 = require("./new");
 const providers_1 = require("./providers");
 const cli_2 = require("./providers/create/cli");
 const cli_ui_1 = require("./utils/cli-ui");
+const main_help_1 = require("./help/main-help");
+const command_help_registry_1 = require("./help/command-help-registry");
 const scripts_1 = require("./scripts");
 const studio_1 = require("./studio");
 /**
  * The current version of the ExpressoTS Bundle.
- * core, adapters, and cli.
+ * Derived from this CLI package's own package.json — single source of truth.
+ * The compiled binary lives at `bin/cli.js`, so the package.json is one
+ * directory above `__dirname`. When running from source via tsx the layout
+ * is `src/cli.ts` -> `../package.json`, which still resolves correctly.
  */
-exports.BUNDLE_VERSION = "4.0.0-preview.2";
-(0, cli_ui_1.printHeader)();
+function readBundleVersion() {
+    try {
+        const pkgPath = (0, path_1.resolve)(__dirname, "..", "package.json");
+        const pkg = JSON.parse((0, fs_1.readFileSync)(pkgPath, "utf8"));
+        if (typeof pkg.version === "string" && pkg.version.length > 0) {
+            return pkg.version;
+        }
+    }
+    catch {
+        // fall through to the safe default below
+    }
+    return "0.0.0";
+}
+exports.BUNDLE_VERSION = readBundleVersion();
+// Respect the NO_COLOR convention (https://no-color.org). chalk v4 does
+// not auto-detect this, so we disable color output explicitly when the
+// variable is present (regardless of its value).
+if (process.env.NO_COLOR !== undefined) {
+    chalk_1.default.level = 0;
+}
+// Intercept the *top-level* help (and the bare no-command invocation)
+// to render our refined, grouped help screen instead of the sprawling
+// default yargs output. Per-command help (e.g. `new --help`) is left to
+// yargs so its rich, command-specific epilogs still work.
+const cliArgs = (0, helpers_1.hideBin)(process.argv);
+const TOP_LEVEL_HELP_TOKENS = new Set(["help", "--help", "-h"]);
+const isTopLevelHelp = cliArgs.length === 0 ||
+    (cliArgs.length === 1 && TOP_LEVEL_HELP_TOKENS.has(cliArgs[0]));
+if (isTopLevelHelp) {
+    (0, main_help_1.printMainHelp)(exports.BUNDLE_VERSION);
+    process.exit(0);
+}
+// Intercept per-command help (e.g. `costs --help`) for commands that have a
+// registered spec, rendering the same refined, grouped screen as the rest of
+// the CLI. Commands without a spec fall through to yargs' default help.
+if ((0, command_help_registry_1.tryPrintCommandHelp)(cliArgs, exports.BUNDLE_VERSION)) {
+    process.exit(0);
+}
+// Only show the banner in interactive terminals. When output is piped
+// (CI, file redirection, shell completion), the header would be noise.
+if (process.stdout.isTTY) {
+    (0, cli_ui_1.printHeader)(exports.BUNDLE_VERSION);
+}
 (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
     .scriptName("expressots")
     .command((0, new_1.createProject)())
@@ -52,6 +100,7 @@ exports.BUNDLE_VERSION = "4.0.0-preview.2";
     .command((0, studio_1.studioCommand)())
     .command((0, info_1.infoProject)())
     .command((0, cli_1.helpCommand)())
+    .completion("completion", "Generate a shell completion script (bash/zsh)")
     .demandCommand(1, "You need at least one command before moving on")
     .strict()
     .fail((msg, err, yargs) => {
@@ -79,10 +128,11 @@ exports.BUNDLE_VERSION = "4.0.0-preview.2";
     process.exit(1);
 })
     .epilog(`${chalk_1.default.bold.green("For more information:")} \n\n` +
-    "🌐 visit:\t https://expresso-ts.com\n" +
-    "💖 Sponsor:\t https://github.com/sponsors/expressots")
+    `${"🌐 visit:".padEnd(12)} https://expresso-ts.com\n` +
+    `${"💖 Sponsor:".padEnd(12)} https://github.com/sponsors/expressots`)
     .help("help", "Show command help")
     .alias("h", "help")
-    .version(false)
+    .version(exports.BUNDLE_VERSION)
+    .alias("V", "version")
     .wrap(140)
     .parse();

package/bin/commands/project.commands.js

@@ -36,7 +36,95 @@ const cli_ui_1 = require("../utils/cli-ui");
 const compiler_1 = __importDefault(require("../utils/compiler"));
 const safe_spawn_1 = require("../utils/safe-spawn");
 /**
- * Helper function to load and extract outDir from tsconfig.build.json
+ * Resolve a tsconfig.json file with full `extends` chain support.
+ * Recursively loads the base config(s) and merges `compilerOptions`
+ * (child wins), producing the same flattened result that `tsc` sees.
+ */
+function resolveTsConfig(configPath) {
+    if (!(0, fs_1.existsSync)(configPath)) {
+        return {};
+    }
+    let raw;
+    try {
+        raw = (0, fs_1.readFileSync)(configPath, "utf-8");
+    }
+    catch {
+        return {};
+    }
+    // tsconfig.json allows JS-style comments but JSON.parse does not.
+    // We strip them character-by-character so we never touch `//` or
+    // `/*` sequences that appear inside quoted strings (e.g. paths).
+    const stripped = stripJsonComments(raw);
+    let config;
+    try {
+        config = JSON.parse(stripped);
+    }
+    catch {
+        return {};
+    }
+    if (typeof config.extends === "string") {
+        const baseRelative = config.extends;
+        const basePath = path_1.default.resolve(path_1.default.dirname(configPath), baseRelative);
+        const baseConfig = resolveTsConfig(basePath);
+        const baseOpts = baseConfig.compilerOptions ?? {};
+        const childOpts = config.compilerOptions ?? {};
+        config.compilerOptions = { ...baseOpts, ...childOpts };
+        delete config.extends;
+    }
+    return config;
+}
+// Strip JS-style comments (single-line and block) from a JSON string
+// without corrupting quoted content. Walks the input character by
+// character, tracking whether we are inside a string literal.
+function stripJsonComments(text) {
+    let result = "";
+    let i = 0;
+    const len = text.length;
+    while (i < len) {
+        const ch = text[i];
+        // String literal — copy verbatim until the closing quote.
+        if (ch === '"') {
+            let j = i + 1;
+            while (j < len) {
+                if (text[j] === "\\") {
+                    j += 2; // skip escaped character
+                }
+                else if (text[j] === '"') {
+                    j++;
+                    break;
+                }
+                else {
+                    j++;
+                }
+            }
+            result += text.slice(i, j);
+            i = j;
+            continue;
+        }
+        // Single-line comment
+        if (ch === "/" && text[i + 1] === "/") {
+            // Skip until end of line.
+            i += 2;
+            while (i < len && text[i] !== "\n")
+                i++;
+            continue;
+        }
+        // Multi-line comment
+        if (ch === "/" && text[i + 1] === "*") {
+            i += 2;
+            while (i < len && !(text[i] === "*" && text[i + 1] === "/"))
+                i++;
+            i += 2; // skip closing */
+            continue;
+        }
+        result += ch;
+        i++;
+    }
+    return result;
+}
+/**
+ * Helper function to load and extract outDir from tsconfig.build.json,
+ * resolving the `extends` chain so the value can live in the base config.
  */
 function getOutDir() {
     const tsconfigBuildPath = (0, path_1.join)(process.cwd(), "tsconfig.build.json");
@@ -44,17 +132,11 @@ function getOutDir() {
         (0, cli_ui_1.printError)("Cannot find tsconfig.build.json. Please create one in the root directory", "tsconfig-build-path");
         process.exit(1);
     }
-    let tsconfig;
-    try {
-        tsconfig = JSON.parse((0, fs_1.readFileSync)(tsconfigBuildPath, "utf-8"));
-    }
-    catch (err) {
-        (0, cli_ui_1.printError)(`Failed to parse tsconfig.build.json: ${err.message}`, "tsconfig-build-path");
-        process.exit(1);
-    }
-    const outDir = tsconfig.compilerOptions?.outDir;
+    const tsconfig = resolveTsConfig(tsconfigBuildPath);
+    const opts = tsconfig.compilerOptions;
+    const outDir = opts?.outDir;
     if (!outDir) {
-        (0, cli_ui_1.printError)("Cannot find outDir in tsconfig.build.json. Please provide an outDir.", "tsconfig-build-path");
+        (0, cli_ui_1.printError)("Cannot find outDir in tsconfig.build.json (or its extended config). Please provide an outDir.", "tsconfig-build-path");
         process.exit(1);
     }
     if (!(0, fs_1.existsSync)(outDir)) {
@@ -147,6 +229,86 @@ exports.prodCommand = {
         await (0, exports.runCommand)({ command: "prod" });
     },
 };
+/**
+ * Recursively collect the PIDs of every descendant of `rootPid`.
+ *
+ * `tsx --watch` exits immediately on SIGINT/SIGTERM and *abandons* the
+ * server process it spawned, so the server is still running its graceful
+ * shutdown after `tsx` is gone. To wait for it we snapshot the process
+ * tree (while it's still attached to `tsx`) and later poll those PIDs.
+ *
+ * Returns an empty list on Windows (no `ps`) or if the lookup fails, in
+ * which case the caller simply skips the wait.
+ */
+function getDescendantPids(rootPid) {
+    if (process.platform === "win32" || !rootPid || rootPid < 0) {
+        return [];
+    }
+    try {
+        const res = (0, safe_spawn_1.safeSpawnSync)("ps", ["-A", "-o", "pid=,ppid="], {
+            encoding: "utf-8",
+        });
+        const out = res.stdout ? String(res.stdout) : "";
+        const childrenByParent = new Map();
+        for (const line of out.split("\n")) {
+            const match = line.trim().match(/^(\d+)\s+(\d+)$/);
+            if (!match)
+                continue;
+            const pid = Number(match[1]);
+            const ppid = Number(match[2]);
+            const siblings = childrenByParent.get(ppid) ?? [];
+            siblings.push(pid);
+            childrenByParent.set(ppid, siblings);
+        }
+        const descendants = [];
+        const stack = [rootPid];
+        while (stack.length > 0) {
+            const current = stack.pop();
+            for (const child of childrenByParent.get(current) ?? []) {
+                descendants.push(child);
+                stack.push(child);
+            }
+        }
+        return descendants;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Check whether a process is still alive. `process.kill(pid, 0)` sends no
+ * signal but performs the permission/existence check: ESRCH means gone,
+ * EPERM means alive but owned by another user.
+ */
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/**
+ * Resolve once every PID in `pids` has exited, or once `timeoutMs` elapses.
+ */
+function waitForPidsToExit(pids, timeoutMs) {
+    return new Promise((resolve) => {
+        if (pids.length === 0) {
+            resolve();
+            return;
+        }
+        const deadline = Date.now() + timeoutMs;
+        const poll = () => {
+            if (Date.now() >= deadline || !pids.some(isPidAlive)) {
+                resolve();
+                return;
+            }
+            setTimeout(poll, 50);
+        };
+        poll();
+    });
+}
 /**
  * Helper function to execute a command
  * @param command The command to execute
@@ -164,12 +326,60 @@ function execCmd(command, args, cwd = process.cwd()) {
             stdio: "inherit",
             cwd,
         });
-        proc.on("error", (err) => reject(err));
-        proc.on("close", (code) => {
-            if (code === 0) {
-                resolve();
+        // On Ctrl+C the SIGINT hits the whole foreground process group, so
+        // the spawned process (and the server it runs) already receive it.
+        // We keep *this* (parent) process alive — instead of dying from the
+        // default signal behavior — so the shell doesn't redraw its prompt
+        // until the server has finished shutting down. We also snapshot the
+        // child process tree on the first signal: `tsx --watch` exits right
+        // away and abandons the server, so we remember the server PID(s) to
+        // wait on them after `tsx` is gone.
+        let descendantPids = [];
+        let signalled = false;
+        const onSignal = () => {
+            if (signalled)
+                return;
+            signalled = true;
+            descendantPids = getDescendantPids(proc.pid ?? -1);
+        };
+        process.on("SIGINT", onSignal);
+        process.on("SIGTERM", onSignal);
+        const cleanup = () => {
+            process.removeListener("SIGINT", onSignal);
+            process.removeListener("SIGTERM", onSignal);
+        };
+        proc.on("error", (err) => {
+            cleanup();
+            reject(err);
+        });
+        proc.on("close", (code, signal) => {
+            // Exit codes 130 (SIGINT) and 143 (SIGTERM) mean the user or
+            // orchestrator intentionally stopped the process — not a failure.
+            const isSignalExit = signalled ||
+                code === 130 ||
+                code === 143 ||
+                signal === "SIGINT" ||
+                signal === "SIGTERM";
+            if (code === 0 || isSignalExit) {
+                if (isSignalExit) {
+                    // The server (a `tsx --watch` grandchild) may still be
+                    // finishing its graceful shutdown after `tsx` itself has
+                    // exited. Wait for it to fully terminate so its final
+                    // "Graceful shutdown completed" log lands before the shell
+                    // prompt returns. The 9s cap matches the framework's own
+                    // shutdown watchdog (default timeout + buffer).
+                    void waitForPidsToExit(descendantPids, 9000).then(() => {
+                        cleanup();
+                        resolve();
+                    });
+                }
+                else {
+                    cleanup();
+                    resolve();
+                }
             }
             else {
+                cleanup();
                 reject(new Error(`Command failed with code ${code}`));
             }
         });
@@ -201,17 +411,14 @@ const transformPathAliases = async (outDir) => {
     if (!(0, fs_1.existsSync)(tsconfigPath)) {
         return; // No tsconfig.build.json, skip transformation
     }
-    let tsconfig;
-    try {
-        tsconfig = JSON.parse((0, fs_1.readFileSync)(tsconfigPath, "utf-8"));
-    }
-    catch (err) {
-        (0, cli_ui_1.printError)(`Failed to parse tsconfig.build.json for path-alias transform: ${err.message}`, "transform-paths");
-        return;
-    }
-    const paths = tsconfig.compilerOptions?.paths;
-    const baseUrl = tsconfig.compilerOptions?.baseUrl;
-    if (!paths || !baseUrl) {
+    const tsconfig = resolveTsConfig(tsconfigPath);
+    const opts = tsconfig.compilerOptions;
+    const paths = opts?.paths;
+    // `baseUrl` is deprecated in TypeScript 7. When it's omitted the path
+    // targets are resolved relative to the tsconfig file itself, which is
+    // the project root in our generated templates — so default to ".".
+    const baseUrl = opts?.baseUrl ?? ".";
+    if (!paths) {
         return; // No path aliases defined, skip
     }
     // Build regex patterns for each alias

package/bin/containerize/cli.d.ts

@@ -1,4 +1,4 @@
 import { CommandModule } from "yargs";
-type CommandModuleArgs = {};
+type CommandModuleArgs = Record<string, never>;
 declare const containerize: () => CommandModule<CommandModuleArgs, any>;
 export { containerize };

package/bin/containerize/cli.js

@@ -6,7 +6,7 @@ const containerize = () => {
     return {
         command: "containerize [target] [environment]",
         describe: "Generate container configurations for your ExpressoTS application.",
-        aliases: ["c"],
+        aliases: ["ctr"],
         builder: (yargs) => {
             yargs.positional("target", {
                 choices: ["docker", "kubernetes", "k8s", "compose"],