@expressots/cli 3.0.0 → 4.0.0-preview.3

package/bin/utils/cli-ui.js

@@ -3,30 +3,150 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.printGenerateSuccess = exports.printGenerateError = exports.printWarning = exports.printSuccess = exports.printError = void 0;
+exports.printHeader = exports.printKeyValue = exports.printDivider = exports.printBullet = exports.printSection = exports.printGenerateSuccess = exports.printGenerateError = exports.printDebug = exports.printInfo = exports.printWarning = exports.printSuccess = exports.printError = void 0;
 const chalk_1 = __importDefault(require("chalk"));
 const process_1 = require("process");
-function printError(message, component) {
-    console.error(chalk_1.default.red(`${message}:`, chalk_1.default.bold(chalk_1.default.white(`[${component}] ❌`))));
+/**
+ * Format timestamp for display (matches core logger format)
+ */
+function formatTimestamp() {
+    const date = new Date();
+    const options = {
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+    };
+    return date.toLocaleString(undefined, options).replace(",", "");
+}
+/**
+ * Color a string based on log level
+ */
+function colorByLevel(level, text) {
+    switch (level) {
+        case "INFO":
+            return chalk_1.default.green(text);
+        case "WARN":
+            return chalk_1.default.yellow(text);
+        case "ERROR":
+            return chalk_1.default.red(text);
+        case "DEBUG":
+            return chalk_1.default.blue(text);
+        default:
+            return chalk_1.default.white(text);
+    }
+}
+/**
+ * Core log function matching ExpressoTS core logger format
+ * Format: [ExpressoTS] timestamp LEVEL [context] message
+ */
+function log(level, context, message, icon) {
+    const timestamp = formatTimestamp();
+    const levelStr = colorByLevel(level, level.padEnd(5, " "));
+    const contextStr = chalk_1.default.green(`[${context}]`);
+    const messageStr = colorByLevel(level, message);
+    const iconStr = icon ? ` ${icon}` : "";
+    const output = `${chalk_1.default.green("[ExpressoTS]")} ${timestamp} ${levelStr} ${contextStr} ${messageStr}${iconStr}\n`;
+    if (level === "ERROR") {
+        process.stderr.write(output);
+    }
+    else {
+        process_1.stdout.write(output);
+    }
+}
+/**
+ * Print error message (matches core logger ERROR format)
+ */
+function printError(message, context) {
+    log("ERROR", context, message, "❌");
 }
 exports.printError = printError;
-function printSuccess(message, component) {
-    process_1.stdout.write(chalk_1.default.green(`${message}:`, chalk_1.default.bold(chalk_1.default.white(`[${component}] ✔️\n`))));
+/**
+ * Print success message (matches core logger INFO format)
+ */
+function printSuccess(message, context) {
+    log("INFO", context, message, "✔️");
 }
 exports.printSuccess = printSuccess;
-function printWarning(message, component) {
-    if (component === undefined) {
-        process_1.stdout.write(chalk_1.default.yellow(`${message} ⚠️\n`));
-        return;
-    }
-    process_1.stdout.write(chalk_1.default.yellow(`${message}:`, chalk_1.default.bold(chalk_1.default.white(`[${component}] ⚠️\n`))));
+/**
+ * Print warning message (matches core logger WARN format)
+ */
+function printWarning(message, context) {
+    log("WARN", context || "cli", message, "⚠️");
 }
 exports.printWarning = printWarning;
+/**
+ * Print info message (matches core logger INFO format)
+ */
+function printInfo(message, context) {
+    log("INFO", context, message);
+}
+exports.printInfo = printInfo;
+/**
+ * Print debug message (matches core logger DEBUG format)
+ */
+function printDebug(message, context) {
+    log("DEBUG", context, message);
+}
+exports.printDebug = printDebug;
+/**
+ * Print generate error (simplified format for scaffolding)
+ */
 async function printGenerateError(schematic, file) {
-    console.error(" ", chalk_1.default.redBright(`[${schematic}]`.padEnd(14)), chalk_1.default.bold.white(`${file.split(".")[0]} not created! ❌`));
+    log("ERROR", schematic, `${file.split(".")[0]} not created!`, "❌");
 }
 exports.printGenerateError = printGenerateError;
+/**
+ * Print generate success (simplified format for scaffolding)
+ */
 async function printGenerateSuccess(schematic, file) {
-    console.log(" ", chalk_1.default.greenBright(`[${schematic}]`.padEnd(14)), chalk_1.default.bold.white(`${file.split(".")[0]} created! ✔️`));
+    log("INFO", schematic, `${file.split(".")[0]} created!`, "✔️");
 }
 exports.printGenerateSuccess = printGenerateSuccess;
+/**
+ * Print a section title. Intended for interactive/listing output (e.g.
+ * `templates list`, `costs compare`) where the structured logger format
+ * (`[ExpressoTS] timestamp LEVEL`) would be noisy. Leading newline keeps
+ * sections visually separated.
+ */
+function printSection(title) {
+    process_1.stdout.write(`\n${chalk_1.default.bold.cyan(title)}\n`);
+}
+exports.printSection = printSection;
+/**
+ * Print an indented bullet point under a section.
+ */
+function printBullet(text) {
+    process_1.stdout.write(`  ${chalk_1.default.gray("-")} ${text}\n`);
+}
+exports.printBullet = printBullet;
+/**
+ * Print a dim horizontal divider sized to the terminal width (capped).
+ */
+function printDivider() {
+    const cols = typeof process.stdout.columns === "number" && process.stdout.columns > 0
+        ? process.stdout.columns
+        : 80;
+    const width = Math.min(Math.max(cols, 20), 80);
+    process_1.stdout.write(`${chalk_1.default.dim("\u2500".repeat(width))}\n`);
+}
+exports.printDivider = printDivider;
+/**
+ * Print an aligned key/value pair (e.g. `Source:  remote`).
+ */
+function printKeyValue(key, value, padding = 12) {
+    process_1.stdout.write(`  ${chalk_1.default.bold(`${key}:`.padEnd(padding))} ${value}\n`);
+}
+exports.printKeyValue = printKeyValue;
+/**
+ * Print the ExpressoTS CLI header
+ */
+function printHeader(version) {
+    const title = version
+        ? `🐎 ExpressoTS CLI v${version}`
+        : "🐎 ExpressoTS CLI";
+    process_1.stdout.write(`\n${chalk_1.default.bold.green(title)}\n\n`);
+}
+exports.printHeader = printHeader;

package/bin/utils/index.d.ts

@@ -1 +1,5 @@
 export * from "./compiler";
+export * from "./input-validation";
+export * from "./package-manager-commands";
+export * from "./safe-spawn";
+export * from "./update-tsconfig-paths";

package/bin/utils/index.js

@@ -15,3 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./compiler"), exports);
+__exportStar(require("./input-validation"), exports);
+__exportStar(require("./package-manager-commands"), exports);
+__exportStar(require("./safe-spawn"), exports);
+__exportStar(require("./update-tsconfig-paths"), exports);

package/bin/utils/input-validation.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ */
+/**
+ * Guard against shell metacharacters in any value that will be
+ * interpolated into a shell-evaluated command line.
+ */
+export declare function containsShellMetachars(value: string): boolean;
+/**
+ * Validate an npm package name (with optional scope).
+ */
+export declare function isValidPackageName(name: unknown): name is string;
+/**
+ * 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 `*`.
+ */
+export declare function isValidVersion(version: unknown): version is string;
+/**
+ * Validate an npm/yarn/pnpm script name.
+ */
+export declare function isValidScriptName(name: unknown): name is string;
+export declare function isValidPackageManager(pm: unknown): pm is "npm" | "yarn" | "pnpm" | "bun";
+/**
+ * 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).
+ */
+export declare function safeResolveWithin(base: string, target: string): string | null;
+/**
+ * Throws a generic `Error` if the value is not a safe package name.
+ */
+export declare function assertValidPackageName(name: unknown): asserts name is string;
+/**
+ * Throws a generic `Error` if the value is not a safe version range.
+ */
+export declare function assertValidVersion(version: unknown): asserts version is string;
+/**
+ * Throws a generic `Error` if the value is not a safe script name.
+ */
+export declare function assertValidScriptName(name: unknown): asserts name is string;

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[];
+};