@expressots/cli 3.0.0 → 4.0.0-preview.2

package/bin/utils/input-validation.js

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * Input validation utilities used across the CLI to defend against
+ * command injection and path traversal when user-supplied values flow
+ * into child_process spawn/exec calls or filesystem writes.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertValidScriptName = exports.assertValidVersion = exports.assertValidPackageName = exports.safeResolveWithin = exports.isValidPackageManager = exports.isValidScriptName = exports.isValidVersion = exports.isValidPackageName = exports.containsShellMetachars = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Characters that have shell-special meaning across POSIX shells and
+ * Windows cmd. If any appear in a value that will be interpolated into
+ * a shell-evaluated command (`shell: true` or `execSync(string)`), the
+ * value must be rejected.
+ */
+const SHELL_METACHARACTERS = /[;&|`$()<>\n\r\\"'*?{}[\]!#~]/;
+/**
+ * Conservative regex for npm package names. Allows scoped packages,
+ * dotted segments and dashes, mirroring https://docs.npmjs.com/cli/v10/configuring-npm/package-json#name
+ * but stricter than npm itself to remove ambiguity (no leading dots,
+ * no uppercase to keep it portable across registries).
+ */
+const PACKAGE_NAME_RE = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+/**
+ * Semver-ish range validator. Accepts the common syntactic shapes
+ * (e.g. 1.2.3, ^1.2, ~1, 1.x, latest, next, >=1.2.3 <2.0.0) without
+ * pulling in the full semver parser for this guard.
+ */
+const VERSION_RE = /^[A-Za-z0-9.\-+~^>=<* |]+$/;
+/**
+ * Script name validator for npm/yarn/pnpm `run` targets. Matches what
+ * those package managers actually accept (alphanumerics plus
+ * `:_-./`), explicitly rejecting whitespace and shell metacharacters.
+ */
+const SCRIPT_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9:_./-]*$/;
+/**
+ * Guard against shell metacharacters in any value that will be
+ * interpolated into a shell-evaluated command line.
+ */
+function containsShellMetachars(value) {
+    return SHELL_METACHARACTERS.test(value);
+}
+exports.containsShellMetachars = containsShellMetachars;
+/**
+ * Validate an npm package name (with optional scope).
+ */
+function isValidPackageName(name) {
+    if (typeof name !== "string" || name.length === 0 || name.length > 214) {
+        return false;
+    }
+    if (containsShellMetachars(name))
+        return false;
+    return PACKAGE_NAME_RE.test(name);
+}
+exports.isValidPackageName = isValidPackageName;
+/**
+ * Validate a version specifier passed to a package manager. Accepts
+ * `latest`, `next`, exact versions and common range syntaxes
+ * (`>=1.2.3 <2.0.0`, `*`, `1.x`). Returns false for the boolean
+ * fallback yargs sometimes assigns when the flag is absent.
+ *
+ * Versions are forwarded via argv (`shell: false`), so we whitelist
+ * the characters npm itself accepts in semver ranges and reject the
+ * rest. We do NOT layer the broader `containsShellMetachars` check
+ * here because legitimate ranges include `<`, `>`, `|`, and `*`.
+ */
+function isValidVersion(version) {
+    if (typeof version !== "string" || version.length === 0)
+        return false;
+    if (version.length > 64)
+        return false;
+    return VERSION_RE.test(version);
+}
+exports.isValidVersion = isValidVersion;
+/**
+ * Validate an npm/yarn/pnpm script name.
+ */
+function isValidScriptName(name) {
+    if (typeof name !== "string" || name.length === 0 || name.length > 214) {
+        return false;
+    }
+    if (containsShellMetachars(name))
+        return false;
+    return SCRIPT_NAME_RE.test(name);
+}
+exports.isValidScriptName = isValidScriptName;
+/**
+ * Validate a package manager identifier.
+ */
+const ALLOWED_PACKAGE_MANAGERS = new Set(["npm", "yarn", "pnpm", "bun"]);
+function isValidPackageManager(pm) {
+    return typeof pm === "string" && ALLOWED_PACKAGE_MANAGERS.has(pm);
+}
+exports.isValidPackageManager = isValidPackageManager;
+/**
+ * Resolve `target` against `base` and verify the result is contained
+ * within `base`. Returns the resolved absolute path on success, or
+ * `null` when the resolved path escapes the base directory (path
+ * traversal attempt).
+ */
+function safeResolveWithin(base, target) {
+    const absoluteBase = node_path_1.default.resolve(base);
+    const absoluteTarget = node_path_1.default.resolve(absoluteBase, target);
+    const baseWithSep = absoluteBase.endsWith(node_path_1.default.sep)
+        ? absoluteBase
+        : absoluteBase + node_path_1.default.sep;
+    if (absoluteTarget !== absoluteBase &&
+        !absoluteTarget.startsWith(baseWithSep)) {
+        return null;
+    }
+    return absoluteTarget;
+}
+exports.safeResolveWithin = safeResolveWithin;
+/**
+ * Throws a generic `Error` if the value is not a safe package name.
+ */
+function assertValidPackageName(name) {
+    if (!isValidPackageName(name)) {
+        throw new Error(`Invalid package name: ${JSON.stringify(name)}. Names must match npm package name rules and contain no shell metacharacters.`);
+    }
+}
+exports.assertValidPackageName = assertValidPackageName;
+/**
+ * Throws a generic `Error` if the value is not a safe version range.
+ */
+function assertValidVersion(version) {
+    if (!isValidVersion(version)) {
+        throw new Error(`Invalid version specifier: ${JSON.stringify(version)}.`);
+    }
+}
+exports.assertValidVersion = assertValidVersion;
+/**
+ * Throws a generic `Error` if the value is not a safe script name.
+ */
+function assertValidScriptName(name) {
+    if (!isValidScriptName(name)) {
+        throw new Error(`Invalid script name: ${JSON.stringify(name)}. Script names must match ^[a-zA-Z0-9][a-zA-Z0-9:_./-]*$.`);
+    }
+}
+exports.assertValidScriptName = assertValidScriptName;

package/bin/utils/package-manager-commands.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared package-manager command helpers for code generators
+ * (Dockerfiles, CI/CD pipelines). These centralize the mapping
+ * between an analyzer-detected package manager and the literal
+ * shell strings emitted into generated files.
+ *
+ * Two flavors exist:
+ *   - `RUN`/`CMD`-style strings used INSIDE Dockerfiles.
+ *   - Plain shell invocations used in CI scripts and informational
+ *     comments (no `RUN ` prefix).
+ */
+export type SupportedPackageManager = "npm" | "yarn" | "pnpm" | "bun";
+/**
+ * Shell invocation that installs project dependencies, suitable for
+ * a CI step (no `RUN ` prefix). Uses the strict, lockfile-respecting
+ * variant for each package manager because CI runs should be
+ * reproducible.
+ */
+export declare function getCiInstallCommand(packageManager: string): string;
+/**
+ * Shell invocation that runs an npm-style script (e.g. `lint`,
+ * `test`, `build`). Used in CI scripts and informational comments.
+ */
+export declare function getRunScriptCommand(packageManager: string, scriptName: string): string;

package/bin/utils/package-manager-commands.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * Shared package-manager command helpers for code generators
+ * (Dockerfiles, CI/CD pipelines). These centralize the mapping
+ * between an analyzer-detected package manager and the literal
+ * shell strings emitted into generated files.
+ *
+ * Two flavors exist:
+ *   - `RUN`/`CMD`-style strings used INSIDE Dockerfiles.
+ *   - Plain shell invocations used in CI scripts and informational
+ *     comments (no `RUN ` prefix).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRunScriptCommand = exports.getCiInstallCommand = void 0;
+/**
+ * Shell invocation that installs project dependencies, suitable for
+ * a CI step (no `RUN ` prefix). Uses the strict, lockfile-respecting
+ * variant for each package manager because CI runs should be
+ * reproducible.
+ */
+function getCiInstallCommand(packageManager) {
+    switch (packageManager) {
+        case "pnpm":
+            return "pnpm install --frozen-lockfile";
+        case "yarn":
+            return "yarn install --frozen-lockfile";
+        case "bun":
+            return "bun install --frozen-lockfile";
+        default:
+            return "npm ci";
+    }
+}
+exports.getCiInstallCommand = getCiInstallCommand;
+/**
+ * Shell invocation that runs an npm-style script (e.g. `lint`,
+ * `test`, `build`). Used in CI scripts and informational comments.
+ */
+function getRunScriptCommand(packageManager, scriptName) {
+    switch (packageManager) {
+        case "pnpm":
+            return `pnpm run ${scriptName}`;
+        case "yarn":
+            return `yarn ${scriptName}`;
+        case "bun":
+            return `bun run ${scriptName}`;
+        default:
+            return `npm run ${scriptName}`;
+    }
+}
+exports.getRunScriptCommand = getRunScriptCommand;

package/bin/utils/safe-spawn.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Cross-platform wrappers around `child_process.spawn` / `spawnSync` for
+ * launching package-manager binaries (npm, yarn, pnpm, npx, tsx, tsc,
+ * docker, etc.) reliably on every supported platform.
+ *
+ * Why this exists
+ * ---------------
+ * Starting with Node.js 18.20.2 / 20.12.2 / 21.7.3 (and every v22+), the
+ * runtime refuses to spawn `.bat` / `.cmd` files unless `shell: true` is
+ * passed (see CVE-2024-27980). On Windows, `npm`, `yarn`, `pnpm`, `npx`,
+ * `tsx`, `tsc`, and the `node_modules/.bin/*` shims are all `.cmd` files,
+ * so a direct `spawn("npm", [...], { shell: false })` call now fails with
+ * `EINVAL` ("Package manager not found"). At the same time, just flipping
+ * `shell: true` reintroduces the original CVE: arguments containing shell
+ * metacharacters (`|`, `>`, `<`, `^`, `&`, `(`, `)`, ...) get interpreted
+ * by `cmd.exe` instead of being passed verbatim, which is a real concern
+ * for inputs like a semver range (`>=1.0.0 <2.0.0`) or a user-supplied
+ * `--src` flag.
+ *
+ * `cross-spawn` solves both problems:
+ *   - On Windows it parses the command, resolves `.cmd` shims via PATHEXT,
+ *     and invokes `cmd.exe /d /s /c "command args"` with `shell: false` and
+ *     `windowsVerbatimArguments: true`. Each argv entry is passed through a
+ *     cmd.exe-aware escaper, so metacharacters stay literal.
+ *   - On Unix it falls through to plain `spawn` with `shell: false`.
+ *
+ * The helpers here are thin wrappers that default `windowsHide: true` so
+ * the Windows console doesn't flash, and re-export the same options shape
+ * as `child_process` for drop-in usage.
+ */
+/// <reference types="node" />
+/// <reference types="node" />
+import type { ChildProcess, SpawnOptions, SpawnSyncOptions, SpawnSyncReturns } from "node:child_process";
+export declare function safeSpawn(command: string, args?: ReadonlyArray<string>, options?: SpawnOptions): ChildProcess;
+export declare function safeSpawnSync(command: string, args?: ReadonlyArray<string>, options?: SpawnSyncOptions): SpawnSyncReturns<Buffer>;

package/bin/utils/safe-spawn.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Cross-platform wrappers around `child_process.spawn` / `spawnSync` for
+ * launching package-manager binaries (npm, yarn, pnpm, npx, tsx, tsc,
+ * docker, etc.) reliably on every supported platform.
+ *
+ * Why this exists
+ * ---------------
+ * Starting with Node.js 18.20.2 / 20.12.2 / 21.7.3 (and every v22+), the
+ * runtime refuses to spawn `.bat` / `.cmd` files unless `shell: true` is
+ * passed (see CVE-2024-27980). On Windows, `npm`, `yarn`, `pnpm`, `npx`,
+ * `tsx`, `tsc`, and the `node_modules/.bin/*` shims are all `.cmd` files,
+ * so a direct `spawn("npm", [...], { shell: false })` call now fails with
+ * `EINVAL` ("Package manager not found"). At the same time, just flipping
+ * `shell: true` reintroduces the original CVE: arguments containing shell
+ * metacharacters (`|`, `>`, `<`, `^`, `&`, `(`, `)`, ...) get interpreted
+ * by `cmd.exe` instead of being passed verbatim, which is a real concern
+ * for inputs like a semver range (`>=1.0.0 <2.0.0`) or a user-supplied
+ * `--src` flag.
+ *
+ * `cross-spawn` solves both problems:
+ *   - On Windows it parses the command, resolves `.cmd` shims via PATHEXT,
+ *     and invokes `cmd.exe /d /s /c "command args"` with `shell: false` and
+ *     `windowsVerbatimArguments: true`. Each argv entry is passed through a
+ *     cmd.exe-aware escaper, so metacharacters stay literal.
+ *   - On Unix it falls through to plain `spawn` with `shell: false`.
+ *
+ * The helpers here are thin wrappers that default `windowsHide: true` so
+ * the Windows console doesn't flash, and re-export the same options shape
+ * as `child_process` for drop-in usage.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeSpawnSync = exports.safeSpawn = void 0;
+const cross_spawn_1 = __importDefault(require("cross-spawn"));
+function safeSpawn(command, args = [], options = {}) {
+    return (0, cross_spawn_1.default)(command, args, {
+        windowsHide: true,
+        ...options,
+    });
+}
+exports.safeSpawn = safeSpawn;
+function safeSpawnSync(command, args = [], options = {}) {
+    return cross_spawn_1.default.sync(command, args, {
+        windowsHide: true,
+        ...options,
+    });
+}
+exports.safeSpawnSync = safeSpawnSync;

package/bin/utils/update-tsconfig-paths.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Generate path alias from folder name
+ * Handles both default mappings and custom folder names
+ *
+ * @param folderName - The folder name (e.g., "useCases", "my-custom-folder")
+ * @returns The path alias (e.g., "@useCases", "@myCustomFolder")
+ */
+export declare function generatePathAlias(folderName: string): string;
+/**
+ * Update tsconfig.json paths to include missing aliases for opinionated scaffolding
+ * Handles both default folders and custom scaffoldSchematics overrides
+ *
+ * @param folderName - The folder name where the schematic is being created
+ * @param sourceRoot - The source root directory (default: "src")
+ */
+export declare function updateTsconfigPaths(folderName: string, sourceRoot?: string): Promise<void>;
+/**
+ * Get the path alias for a given folder name
+ * Used by other utilities to determine the correct import path
+ *
+ * @param folderName - The folder name
+ * @returns The path alias (e.g., "@useCases")
+ */
+export declare function getPathAliasForFolder(folderName: string): string;
+/**
+ * Check if tsconfig already has all required path aliases for opinionated mode
+ * This can be used to validate project setup
+ *
+ * @param requiredFolders - List of folder names that need path aliases
+ * @returns Object with missing aliases and whether all are present
+ */
+export declare function validateTsconfigPaths(requiredFolders: string[]): {
+    valid: boolean;
+    missingAliases: string[];
+};

package/bin/utils/update-tsconfig-paths.js

@@ -0,0 +1,286 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateTsconfigPaths = exports.getPathAliasForFolder = exports.updateTsconfigPaths = exports.generatePathAlias = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const cli_ui_1 = require("./cli-ui");
+/**
+ * Default path alias mappings for opinionated scaffolding
+ * Maps folder names to their corresponding path aliases
+ */
+const DEFAULT_PATH_ALIASES = {
+    controllers: "@controllers",
+    useCases: "@useCases",
+    providers: "@providers",
+    entities: "@entities",
+    middleware: "@middleware",
+    interceptors: "@interceptors",
+    events: "@events",
+    guards: "@guards",
+    config: "@config",
+};
+/**
+ * Generate path alias from folder name
+ * Handles both default mappings and custom folder names
+ *
+ * @param folderName - The folder name (e.g., "useCases", "my-custom-folder")
+ * @returns The path alias (e.g., "@useCases", "@myCustomFolder")
+ */
+function generatePathAlias(folderName) {
+    // Check if we have a default mapping
+    if (DEFAULT_PATH_ALIASES[folderName]) {
+        return DEFAULT_PATH_ALIASES[folderName];
+    }
+    // For custom folder names, convert to camelCase and add @ prefix
+    // Handles: kebab-case, snake_case, PascalCase, camelCase
+    const camelCase = folderName
+        .split(/[-_]/)
+        .map((word, index) => {
+        if (index === 0) {
+            // First word: keep original case for already camelCase names
+            return word.charAt(0).toLowerCase() + word.slice(1);
+        }
+        // Subsequent words: capitalize first letter
+        return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
+    })
+        .join("");
+    return `@${camelCase}`;
+}
+exports.generatePathAlias = generatePathAlias;
+/**
+ * Parse JSONC (JSON with Comments) by stripping comments and trailing commas
+ * Handles:
+ * - Single-line comments (//)
+ * - Multi-line comments
+ * - Trailing commas (common in tsconfig.json)
+ *
+ * @param content - The JSONC content
+ * @returns Cleaned JSON string that can be parsed by JSON.parse
+ */
+function stripJsonComments(content) {
+    let result = content;
+    // Remove multi-line comments first (they can span multiple lines)
+    result = result.replace(/\/\*[\s\S]*?\*\//g, "");
+    // Remove single-line comments (but not inside strings)
+    // This regex looks for // that are not inside strings
+    result = result.replace(/^(\s*)\/\/.*$/gm, "$1");
+    // Also handle inline comments after values
+    // Match: value, // comment or value // comment
+    result = result.replace(/,\s*\/\/.*$/gm, ",");
+    result = result.replace(/(["\d\w\]}\s])\s*\/\/.*$/gm, "$1");
+    // Remove trailing commas before } or ]
+    // This handles cases like: { "key": "value", }
+    result = result.replace(/,(\s*[}\]])/g, "$1");
+    return result;
+}
+/**
+ * Try to parse JSONC content, first stripping comments then parsing
+ * @param content - Raw file content
+ * @returns Parsed config object or null if parsing fails
+ */
+function parseJsonc(content) {
+    // Always try to strip comments first for consistency
+    const stripped = stripJsonComments(content);
+    try {
+        return JSON.parse(stripped);
+    }
+    catch {
+        // If stripping didn't help, try the original (unlikely but safe)
+        try {
+            return JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/**
+ * Text-based fallback to add path alias when JSON parsing fails
+ * This preserves the original file format (comments, etc.)
+ *
+ * @param content - Original file content
+ * @param aliasKey - The path alias key (e.g., "@config/*")
+ * @param aliasValue - The path alias value (e.g., ["./src/config/*"])
+ * @returns Modified content or null if update failed
+ */
+function addPathAliasTextBased(content, aliasKey, aliasValue) {
+    // Check if the alias already exists
+    if (content.includes(`"${aliasKey}"`)) {
+        return null; // Already exists, no update needed
+    }
+    // Find the "paths" object
+    const pathsMatch = content.match(/"paths"\s*:\s*\{/);
+    if (pathsMatch && pathsMatch.index !== undefined) {
+        // Insert new path alias after "paths": {
+        const insertPos = pathsMatch.index + pathsMatch[0].length;
+        const aliasEntry = `\n\t\t\t"${aliasKey}": ${JSON.stringify(aliasValue)},`;
+        return (content.slice(0, insertPos) + aliasEntry + content.slice(insertPos));
+    }
+    // Find compilerOptions to add paths object
+    const compilerOptionsMatch = content.match(/"compilerOptions"\s*:\s*\{/);
+    if (compilerOptionsMatch && compilerOptionsMatch.index !== undefined) {
+        // Check if baseUrl exists
+        const hasBaseUrl = /"baseUrl"\s*:/.test(content);
+        // Find the end of compilerOptions opening brace
+        const insertPos = compilerOptionsMatch.index + compilerOptionsMatch[0].length;
+        let insertion = "\n";
+        if (!hasBaseUrl) {
+            insertion += '\t\t"baseUrl": ".",\n';
+        }
+        insertion += `\t\t"paths": {\n\t\t\t"${aliasKey}": ${JSON.stringify(aliasValue)}\n\t\t},`;
+        return (content.slice(0, insertPos) + insertion + content.slice(insertPos));
+    }
+    // Can't find compilerOptions, give up
+    return null;
+}
+/**
+ * Update tsconfig.json paths to include missing aliases for opinionated scaffolding
+ * Handles both default folders and custom scaffoldSchematics overrides
+ *
+ * @param folderName - The folder name where the schematic is being created
+ * @param sourceRoot - The source root directory (default: "src")
+ */
+async function updateTsconfigPaths(folderName, sourceRoot = "src") {
+    if (!folderName) {
+        return; // No folder specified
+    }
+    const tsconfigPath = node_path_1.default.join(process.cwd(), "tsconfig.json");
+    const tsconfigBuildPath = node_path_1.default.join(process.cwd(), "tsconfig.build.json");
+    // Generate alias from folder name (handles custom names)
+    const alias = generatePathAlias(folderName);
+    const aliasKey = `${alias}/*`;
+    // Track if we updated any config
+    let updated = false;
+    // Update both tsconfig files if they exist
+    for (const configPath of [tsconfigPath, tsconfigBuildPath]) {
+        if (!node_fs_1.default.existsSync(configPath)) {
+            continue;
+        }
+        try {
+            const configContent = node_fs_1.default.readFileSync(configPath, "utf-8");
+            // Try JSON parsing first
+            const config = parseJsonc(configContent);
+            if (config) {
+                // JSON parsing succeeded - use structured approach
+                // Ensure compilerOptions exists
+                if (!config.compilerOptions) {
+                    config.compilerOptions = {};
+                }
+                const compilerOptions = config.compilerOptions;
+                // Ensure baseUrl is set (required for paths to work)
+                if (!compilerOptions.baseUrl) {
+                    compilerOptions.baseUrl = ".";
+                }
+                // Determine the correct path value based on baseUrl
+                // If baseUrl is "./src" or "src", paths should be relative to src
+                // If baseUrl is ".", paths should include the full path from root
+                const baseUrl = compilerOptions.baseUrl || ".";
+                const isBaseUrlSrc = baseUrl === `./${sourceRoot}` || baseUrl === sourceRoot;
+                const aliasValue = isBaseUrlSrc
+                    ? [`./${folderName}/*`]
+                    : [`./${sourceRoot}/${folderName}/*`];
+                // Ensure paths object exists
+                if (!compilerOptions.paths) {
+                    compilerOptions.paths = {};
+                }
+                const paths = compilerOptions.paths;
+                // Only add if it doesn't exist
+                if (!paths[aliasKey]) {
+                    paths[aliasKey] = aliasValue;
+                    // Write back to file with proper formatting (tab indent)
+                    node_fs_1.default.writeFileSync(configPath, JSON.stringify(config, null, "\t") + "\n", "utf-8");
+                    updated = true;
+                }
+            }
+            else {
+                // JSON parsing failed - use text-based fallback
+                // This preserves comments and formatting
+                // Try to detect baseUrl from content
+                const baseUrlMatch = configContent.match(/"baseUrl"\s*:\s*"([^"]+)"/);
+                const baseUrl = baseUrlMatch ? baseUrlMatch[1] : ".";
+                const isBaseUrlSrc = baseUrl === `./${sourceRoot}` || baseUrl === sourceRoot;
+                const aliasValue = isBaseUrlSrc
+                    ? [`./${folderName}/*`]
+                    : [`./${sourceRoot}/${folderName}/*`];
+                const modifiedContent = addPathAliasTextBased(configContent, aliasKey, aliasValue);
+                if (modifiedContent) {
+                    node_fs_1.default.writeFileSync(configPath, modifiedContent, "utf-8");
+                    updated = true;
+                }
+                else if (!configContent.includes(`"${aliasKey}"`)) {
+                    // Couldn't update and alias doesn't exist
+                    (0, cli_ui_1.printWarning)(`Could not update ${node_path_1.default.basename(configPath)}. Please add "${aliasKey}" path alias manually`, "tsconfig");
+                }
+            }
+        }
+        catch (error) {
+            // Log warning but don't fail the scaffolding process
+            (0, cli_ui_1.printWarning)(`Could not update ${node_path_1.default.basename(configPath)}: ${error instanceof Error ? error.message : "Unknown error"}`, "tsconfig");
+        }
+    }
+    // Print success message only if we updated something
+    if (updated) {
+        (0, cli_ui_1.printInfo)(`Path alias ${aliasKey} added`, "tsconfig");
+    }
+}
+exports.updateTsconfigPaths = updateTsconfigPaths;
+/**
+ * Get the path alias for a given folder name
+ * Used by other utilities to determine the correct import path
+ *
+ * @param folderName - The folder name
+ * @returns The path alias (e.g., "@useCases")
+ */
+function getPathAliasForFolder(folderName) {
+    return generatePathAlias(folderName);
+}
+exports.getPathAliasForFolder = getPathAliasForFolder;
+/**
+ * Check if tsconfig already has all required path aliases for opinionated mode
+ * This can be used to validate project setup
+ *
+ * @param requiredFolders - List of folder names that need path aliases
+ * @returns Object with missing aliases and whether all are present
+ */
+function validateTsconfigPaths(requiredFolders) {
+    const tsconfigPath = node_path_1.default.join(process.cwd(), "tsconfig.json");
+    if (!node_fs_1.default.existsSync(tsconfigPath)) {
+        return {
+            valid: false,
+            missingAliases: requiredFolders.map((f) => generatePathAlias(f)),
+        };
+    }
+    try {
+        const configContent = node_fs_1.default.readFileSync(tsconfigPath, "utf-8");
+        let config;
+        try {
+            config = JSON.parse(configContent);
+        }
+        catch {
+            config = JSON.parse(stripJsonComments(configContent));
+        }
+        const paths = config.compilerOptions
+            ?.paths || {};
+        const missingAliases = [];
+        for (const folder of requiredFolders) {
+            const aliasKey = `${generatePathAlias(folder)}/*`;
+            if (!paths[aliasKey]) {
+                missingAliases.push(aliasKey);
+            }
+        }
+        return {
+            valid: missingAliases.length === 0,
+            missingAliases,
+        };
+    }
+    catch {
+        return {
+            valid: false,
+            missingAliases: requiredFolders.map((f) => generatePathAlias(f)),
+        };
+    }
+}
+exports.validateTsconfigPaths = validateTsconfigPaths;