@expressots/cli 3.0.0 → 4.0.0-preview.3

package/bin/commands/project.commands.js

@@ -31,10 +31,100 @@ const child_process_1 = require("child_process");
 const fs_1 = require("fs");
 const os_1 = __importDefault(require("os"));
 const path_1 = __importStar(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
 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");
@@ -42,10 +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);
     }
-    const tsconfig = JSON.parse((0, fs_1.readFileSync)(tsconfigBuildPath, "utf-8"));
-    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)) {
@@ -55,40 +146,63 @@ function getOutDir() {
     return outDir;
 }
 /**
- * Load the configuration from the compiler
- * @param compiler The compiler to load the configuration from
- * @returns The configuration
- */
-async function opinionatedConfig() {
-    const { entryPoint } = await compiler_1.default.loadConfig();
-    const config = [
-        "--watch",
-        "-r",
-        "tsconfig-paths/register",
-        `./src/${entryPoint}.ts`,
-    ];
-    return config;
-}
-/**
- * Load the configuration from the compiler
- * @param compiler The compiler to load the configuration from
- * @returns The configuration
+ * Build the tsx watch arguments for development mode.
+ * Uses tsx's built-in --watch flag for reliable cross-platform file watching
+ * (avoids nodemon + SIGTERM issues on Windows).
+ *
+ * @param opinionated - Whether to use opinionated configuration
+ * @returns The tsx arguments array
  */
-async function nonOpinionatedConfig() {
-    const { entryPoint } = await compiler_1.default.loadConfig();
-    const config = ["--watch", `./src/${entryPoint}.ts`];
-    return config;
+async function buildDevArgs(opinionated) {
+    const { entryPoint, sourceRoot } = await compiler_1.default.loadConfig();
+    const args = ["--watch"];
+    if (opinionated) {
+        args.push("-r", "tsconfig-paths/register");
+    }
+    // Honor `sourceRoot` from expressots.config.ts so projects whose
+    // source lives under a non-default folder (e.g. `api/` or
+    // `services/`) still resolve their entry point correctly.
+    args.push(`./${sourceRoot}/${entryPoint}.ts`);
+    return args;
 }
 /**
  * Dev command module
- * @type {CommandModule<object, object>}
+ * @type {CommandModule<object, DevCommandOptions>}
  * @returns The command module
  */
 exports.devCommand = {
     command: "dev",
     describe: "Start development server.",
-    handler: async () => {
-        await (0, exports.runCommand)({ command: "dev" });
+    builder: {
+        container: {
+            alias: "c",
+            type: "boolean",
+            default: false,
+            description: "Run development inside Docker container",
+        },
+        build: {
+            alias: "b",
+            type: "boolean",
+            default: false,
+            description: "Rebuild container before starting (with --container)",
+        },
+        detach: {
+            alias: "d",
+            type: "boolean",
+            default: false,
+            description: "Run container in background (with --container)",
+        },
+    },
+    handler: async (argv) => {
+        if (argv.container) {
+            await runContainerDev({
+                build: argv.build ?? false,
+                detach: argv.detach ?? false,
+            });
+        }
+        else {
+            await (0, exports.runCommand)({ command: "dev" });
+        }
     },
 };
 /**
@@ -115,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
@@ -124,16 +318,68 @@ exports.prodCommand = {
  */
 function execCmd(command, args, cwd = process.cwd()) {
     return new Promise((resolve, reject) => {
-        const proc = (0, child_process_1.spawn)(command, args, {
+        // `safeSpawn` (cross-spawn) resolves Windows `.cmd` shims (npx,
+        // tsx, tsc, etc.) via PATHEXT and applies cmd.exe-aware escaping
+        // for every argv entry, while falling through to plain `spawn`
+        // with `shell: false` on Unix.
+        const proc = (0, safe_spawn_1.safeSpawn)(command, args, {
             stdio: "inherit",
-            shell: true,
             cwd,
         });
-        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}`));
             }
         });
@@ -153,47 +399,340 @@ const compileTypescript = async () => {
     await execCmd("npx", ["tsc", "-p", "tsconfig.build.json"]);
     (0, cli_ui_1.printSuccess)("Built successfully", "compile-typescript");
 };
+/**
+ * Transform path aliases to relative paths in compiled JavaScript files.
+ * This runs after TypeScript compilation to ensure production builds work
+ * without runtime path resolution.
+ *
+ * @param outDir - The output directory (e.g., "./dist")
+ */
+const transformPathAliases = async (outDir) => {
+    const tsconfigPath = (0, path_1.join)(process.cwd(), "tsconfig.build.json");
+    if (!(0, fs_1.existsSync)(tsconfigPath)) {
+        return; // No tsconfig.build.json, skip transformation
+    }
+    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
+    const aliasPatterns = [];
+    for (const [alias, targets] of Object.entries(paths)) {
+        if (!Array.isArray(targets) || targets.length === 0)
+            continue;
+        // Convert @alias/* to regex pattern
+        // Matches: require("@alias/something") or require('@alias/something')
+        const aliasBase = alias.replace("/*", "");
+        const targetBase = targets[0].replace("/*", "");
+        // Pattern to match require("@alias/...") or require('@alias/...')
+        const pattern = new RegExp(`require\\(["']${aliasBase.replace("@", "\\@")}/([^"']+)["']\\)`, "g");
+        aliasPatterns.push({
+            pattern,
+            alias: aliasBase,
+            target: targetBase,
+        });
+    }
+    if (aliasPatterns.length === 0) {
+        return;
+    }
+    // Recursively find all .js files in outDir
+    const findJsFiles = async (dir) => {
+        const files = [];
+        const entries = await fs_1.promises.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = (0, path_1.join)(dir, entry.name);
+            if (entry.isDirectory()) {
+                files.push(...(await findJsFiles(fullPath)));
+            }
+            else if (entry.name.endsWith(".js")) {
+                files.push(fullPath);
+            }
+        }
+        return files;
+    };
+    const jsFiles = await findJsFiles(outDir);
+    let transformedCount = 0;
+    for (const file of jsFiles) {
+        let content = await fs_1.promises.readFile(file, "utf-8");
+        let modified = false;
+        // Get the directory of the current file relative to outDir
+        const fileDir = path_1.default.dirname(file);
+        for (const { pattern, alias, target } of aliasPatterns) {
+            // Calculate the relative path from this file to the target
+            const targetDir = (0, path_1.join)(outDir, baseUrl.replace("./", ""), target);
+            let relativePath = path_1.default.relative(fileDir, targetDir);
+            // Ensure it starts with ./ or ../
+            if (!relativePath.startsWith(".")) {
+                relativePath = "./" + relativePath;
+            }
+            // Replace Windows backslashes with forward slashes
+            relativePath = relativePath.replace(/\\/g, "/");
+            // Replace the alias with the relative path
+            const newContent = content.replace(pattern, (match, subPath) => {
+                modified = true;
+                return `require("${relativePath}/${subPath}")`;
+            });
+            if (newContent !== content) {
+                content = newContent;
+            }
+        }
+        if (modified) {
+            await fs_1.promises.writeFile(file, content, "utf-8");
+            transformedCount++;
+        }
+    }
+    if (transformedCount > 0) {
+        (0, cli_ui_1.printSuccess)(`Path aliases resolved in ${transformedCount} files`, "transform-paths");
+    }
+};
 /**
  * Helper function to copy files to the dist directory
  */
 const copyFiles = async (outDir) => {
-    const { opinionated } = await compiler_1.default.loadConfig();
-    let filesToCopy = [];
-    if (opinionated) {
-        filesToCopy = [
-            "./register-path.js",
-            "tsconfig.build.json",
-            "package.json",
-        ];
-    }
-    else {
-        filesToCopy = ["tsconfig.json", "package.json"];
+    // Only copy package.json - path aliases are resolved at build time
+    // No need for tsconfig files or register-path.js in production
+    const filesToCopy = ["package.json"];
+    for (const file of filesToCopy) {
+        if ((0, fs_1.existsSync)(file)) {
+            await fs_1.promises.copyFile(file, (0, path_1.join)(outDir, path_1.default.basename(file)));
+        }
     }
-    filesToCopy.forEach((file) => {
-        fs_1.promises.copyFile(file, (0, path_1.join)(outDir, path_1.default.basename(file)));
-    });
 };
 /**
  * Helper function to clear the screen
  */
 const clearScreen = () => {
+    // `cls` and `clear` are built-ins / well-known executables.
+    // Invoking them via `shell: true` is safe here because there are no
+    // user-controlled args, but we keep `windowsHide: true` to suppress
+    // the Windows console flash.
     const platform = os_1.default.platform();
     const command = platform === "win32" ? "cls" : "clear";
-    (0, child_process_1.spawn)(command, { stdio: "inherit", shell: true });
+    (0, child_process_1.spawn)(command, [], { stdio: "inherit", shell: true, windowsHide: true });
 };
+/**
+ * Run development in Docker container with auto-setup
+ * This is the seamless "just works" experience
+ */
+async function runContainerDev(options) {
+    console.log(chalk_1.default.cyan("\n🐳 ExpressoTS Container Development\n"));
+    const cwd = process.cwd();
+    const composeDevFile = (0, path_1.join)(cwd, "docker-compose.development.yml");
+    const dockerfileDevFile = (0, path_1.join)(cwd, "Dockerfile.development");
+    const dockerSetupFile = (0, path_1.join)(cwd, "docker-setup.js");
+    const dockerDepsDir = (0, path_1.join)(cwd, ".docker-deps");
+    const packageDockerJson = (0, path_1.join)(cwd, "package.docker.json");
+    // Check if Docker is running
+    if (!isDockerRunning()) {
+        console.log(chalk_1.default.red("❌ Docker is not running."));
+        console.log(chalk_1.default.gray("   Please start Docker Desktop or Docker daemon."));
+        return;
+    }
+    // Step 1: Auto-generate Docker files if missing
+    if (!(0, fs_1.existsSync)(dockerfileDevFile) || !(0, fs_1.existsSync)(composeDevFile)) {
+        console.log(chalk_1.default.yellow("📝 Docker files not found. Generating..."));
+        try {
+            // Import and run containerize
+            const { containerizeProject } = await Promise.resolve().then(() => __importStar(require("../containerize/form")));
+            await containerizeProject({
+                target: "docker",
+                environment: "development",
+                preset: "standard",
+                analyze: true,
+                skipCompose: false,
+                includeCi: false,
+            });
+            console.log();
+        }
+        catch (error) {
+            console.log(chalk_1.default.red("❌ Failed to generate Docker files."));
+            console.log(chalk_1.default.gray("   Run manually: expressots containerize docker --env development"));
+            return;
+        }
+    }
+    // Step 1.5: Check bootstrap config and create missing env files if needed
+    try {
+        const { analyzeBootstrapConfig, shouldCopyEnvFiles, getEnvFileForEnvironment, } = await Promise.resolve().then(() => __importStar(require("../containerize/analyzers/bootstrap-analyzer")));
+        const bootstrapConfig = await analyzeBootstrapConfig();
+        if (bootstrapConfig.hasEnvFileConfig &&
+            shouldCopyEnvFiles(bootstrapConfig)) {
+            const devEnvFile = getEnvFileForEnvironment(bootstrapConfig, "development");
+            // Check if required env file is missing
+            if (bootstrapConfig.missingEnvFiles.includes(devEnvFile)) {
+                console.log(chalk_1.default.yellow(`⚠️  Required env file missing: ${devEnvFile}`));
+                // Auto-create template if configured or prompt user
+                if (bootstrapConfig.autoCreateTemplate) {
+                    console.log(chalk_1.default.gray(`   Creating template ${devEnvFile}...`));
+                    await createEnvTemplate(cwd, devEnvFile, "development", bootstrapConfig.requiredVariables);
+                    console.log(chalk_1.default.green(`   ✓ Created ${devEnvFile}`));
+                }
+                else {
+                    // Provide helpful instructions
+                    console.log(chalk_1.default.cyan("\n💡 To fix this, either:"));
+                    console.log(chalk_1.default.gray(`   1. Create ${devEnvFile} with your environment variables`));
+                    console.log(chalk_1.default.gray(`   2. Add autoCreateTemplate: true to envFileConfig in bootstrap`));
+                    console.log(chalk_1.default.gray(`   3. Use skipFileLoading: true for container deployments`));
+                    console.log();
+                    // Still continue - the container might work if env vars are set in docker-compose
+                    console.log(chalk_1.default.yellow(`   ⚠️  Container may fail if ${devEnvFile} is required`));
+                    console.log();
+                }
+            }
+            // Show required variables that need to be set
+            if (bootstrapConfig.requiredVariables.length > 0) {
+                console.log(chalk_1.default.cyan("📋 Required environment variables:"));
+                bootstrapConfig.requiredVariables.forEach((varName) => {
+                    console.log(chalk_1.default.gray(`   • ${varName}`));
+                });
+                console.log(chalk_1.default.gray(`   Set these in ${devEnvFile} or docker-compose.development.yml`));
+                console.log();
+            }
+        }
+    }
+    catch (error) {
+        // Non-fatal - continue with container startup
+        console.log(chalk_1.default.gray("   (Bootstrap analysis skipped)"));
+    }
+    // Step 2: Auto-run docker:setup if local dependencies exist
+    if ((0, fs_1.existsSync)(packageDockerJson) && (0, fs_1.existsSync)(dockerSetupFile)) {
+        // Check if .docker-deps needs to be updated
+        const needsSetup = !(0, fs_1.existsSync)(dockerDepsDir) || isDirEmpty(dockerDepsDir);
+        if (needsSetup) {
+            console.log(chalk_1.default.yellow("📦 Setting up local dependencies..."));
+            try {
+                const setupResult = (0, safe_spawn_1.safeSpawnSync)(process.execPath, ["docker-setup.js"], {
+                    cwd,
+                    stdio: "inherit",
+                    encoding: "utf-8",
+                });
+                if (setupResult.error)
+                    throw setupResult.error;
+                if (typeof setupResult.status === "number" &&
+                    setupResult.status !== 0) {
+                    throw new Error(`exited with code ${setupResult.status}`);
+                }
+                console.log();
+            }
+            catch (error) {
+                console.log(chalk_1.default.red("❌ Failed to setup local dependencies."));
+                console.log(chalk_1.default.gray("   Run manually: npm run docker:setup"));
+                return;
+            }
+        }
+    }
+    // Step 3: Start the containers
+    console.log(chalk_1.default.yellow(`📄 Using docker-compose.development.yml`));
+    const args = ["-f", composeDevFile, "up"];
+    if (options.build) {
+        console.log(chalk_1.default.yellow("🔨 Rebuilding containers..."));
+        args.splice(2, 0, "--build");
+    }
+    if (options.detach) {
+        args.push("-d");
+    }
+    console.log(chalk_1.default.yellow("🚀 Starting development containers...\n"));
+    // Print dev info
+    console.log(chalk_1.default.bold("Development Environment:"));
+    console.log(`  🌐 App:      http://localhost:3000`);
+    console.log(`  🔍 Debug:    localhost:9229`);
+    console.log();
+    console.log(chalk_1.default.bold("Commands:"));
+    console.log(`  ${chalk_1.default.gray("expressots dev -c")}           Start containers`);
+    console.log(`  ${chalk_1.default.gray("expressots dev -c -b")}        Rebuild & start`);
+    console.log(`  ${chalk_1.default.gray("expressots dev -c -d")}        Start in background`);
+    console.log(`  ${chalk_1.default.gray("docker-compose -f docker-compose.development.yml down")}  Stop`);
+    console.log();
+    console.log(chalk_1.default.green("🔄 Hot reload enabled - edit files to see changes"));
+    if (!options.detach) {
+        console.log(chalk_1.default.gray("Press Ctrl+C to stop\n"));
+    }
+    // Run docker-compose
+    runDockerComposeCommand(args, cwd, options.detach);
+    if (options.detach) {
+        console.log(chalk_1.default.green("\n✅ Containers started in background."));
+        console.log(chalk_1.default.gray("   View logs: docker-compose -f docker-compose.development.yml logs -f"));
+    }
+}
+/**
+ * Check if Docker is running
+ */
+function isDockerRunning() {
+    const result = (0, safe_spawn_1.safeSpawnSync)("docker", ["info"], {
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    return !result.error && result.status === 0;
+}
+/**
+ * Check if directory is empty
+ */
+function isDirEmpty(dir) {
+    try {
+        const files = (0, fs_1.readdirSync)(dir);
+        return files.length === 0;
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Create an environment template file
+ */
+async function createEnvTemplate(cwd, fileName, environment, requiredVariables) {
+    const filePath = (0, path_1.join)(cwd, fileName);
+    const commonVars = [
+        "PORT=3000",
+        `NODE_ENV=${environment}`,
+        "# Add your environment variables below",
+    ];
+    const requiredVars = requiredVariables.map((key) => `${key}=`);
+    const template = [...commonVars, ...requiredVars].join("\n");
+    await fs_1.promises.writeFile(filePath, template, "utf-8");
+}
+/**
+ * Run docker-compose command
+ */
+function runDockerComposeCommand(args, cwd, detach) {
+    // Try docker compose (v2) first, fall back to docker-compose (v1).
+    // `safeSpawnSync` (cross-spawn) handles platform-specific binary
+    // resolution and cmd.exe-aware argv escaping, so compose file paths
+    // and service names are forwarded as discrete arguments rather than
+    // re-interpreted by the OS shell.
+    const v2 = (0, safe_spawn_1.safeSpawnSync)("docker", ["compose", ...args], {
+        cwd,
+        stdio: "inherit",
+    });
+    if (v2.error || (typeof v2.status === "number" && v2.status !== 0)) {
+        const v1 = (0, safe_spawn_1.safeSpawnSync)("docker-compose", args, {
+            cwd,
+            stdio: "inherit",
+        });
+        if (v1.error || (typeof v1.status === "number" && v1.status !== 0)) {
+            console.log(chalk_1.default.red("Error running docker-compose"));
+        }
+    }
+    // `detach` is honored implicitly by docker compose itself when "-d"
+    // is present in `args`. The previous branch tried to switch between
+    // execSync and spawnSync for that case, which served no real
+    // purpose and made shell injection harder to reason about.
+    void detach;
+}
 /**
  * Helper function to run a command
- * @param command The command to run
+ * @param options The command options
  */
 const runCommand = async ({ command, }) => {
-    const { opinionated, entryPoint } = await compiler_1.default.loadConfig();
+    const { opinionated, entryPoint, sourceRoot } = await compiler_1.default.loadConfig();
     const outDir = getOutDir();
     try {
         switch (command) {
             case "dev":
-                execCmd("tsx", opinionated
-                    ? await opinionatedConfig()
-                    : await nonOpinionatedConfig());
+                await execCmd("tsx", await buildDevArgs(opinionated));
                 break;
             case "build":
                 if (!outDir) {
@@ -202,6 +741,10 @@ const runCommand = async ({ command, }) => {
                 }
                 await cleanDist(outDir);
                 await compileTypescript();
+                // Transform path aliases to relative paths for production
+                if (opinionated) {
+                    await transformPathAliases(outDir);
+                }
                 await copyFiles(outDir);
                 break;
             case "prod": {
@@ -209,19 +752,12 @@ const runCommand = async ({ command, }) => {
                     (0, cli_ui_1.printError)("Cannot run in prod mode. Please provide an outDir in tsconfig.build.json", "prod-command");
                     process.exit(1);
                 }
-                let config = [];
-                if (opinionated) {
-                    config = [
-                        "-r",
-                        `./${outDir}/register-path.js`,
-                        `./${outDir}/src/${entryPoint}.js`,
-                    ];
-                }
-                else {
-                    config = [`./${outDir}/${entryPoint}.js`];
-                }
+                // Honor `sourceRoot` so the compiled entry-point path
+                // matches whatever folder the user configured (the TS
+                // compiler preserves the source tree under `outDir`).
+                const config = [`./${outDir}/${sourceRoot}/${entryPoint}.js`];
                 clearScreen();
-                execCmd("node", config);
+                await execCmd("node", config);
                 break;
             }
             default: