zudojs-cli 0.1.2 → 1.1.0

package/dist/src/templates/monolith/monolith.template.js

@@ -24,6 +24,7 @@
  * │   ├── loggers/
  * │   ├── middlewares/
  * │   ├── models/
+ * │   ├── modules/
  * │   ├── repositories/
  * │   ├── routes/
  * │   ├── services/
@@ -33,20 +34,19 @@
  * ├── tests/
  * ├── package.json
  * ├── tsconfig.json
- * ├── zudojs.config.ts
  * └── README.md
  * ```
  */
+import { ZUDOJS_PACKAGES_VERSION } from "../../constants/index.js";
+import { normalizeName, toPascalCase } from "../../utils/utils.name.js";
+import { RUNTIME_APP_DEPENDENCIES, moduleSpec, renderAppFile, renderModuleFile, renderServerFile, renderServiceFile, renderPnpmWorkspaceFile, } from "../shared/index.js";
 export function generateMonolithFiles(options) {
     const name = options.projectName;
     const nameSlug = name.replace(/[^a-z0-9-]+/gi, "-").toLowerCase();
     const deps = [
-        "@zudojs/core",
-        "@zudojs/container",
+        ...RUNTIME_APP_DEPENDENCIES,
         "@zudojs/config",
-        "@zudojs/logger",
         "@zudojs/errors",
-        "@zudojs/constants",
         "@zudojs/types",
         "@zudojs/validation",
         "@zudojs/schema",
@@ -67,7 +67,12 @@ export function generateMonolithFiles(options) {
     if (options.enableOpenAPI) {
         deps.push("@zudojs/openapi");
     }
-    const devDeps = ["tsx", "typescript", "@types/node", "vitest"];
+    const devDeps = {
+        tsx: "^4.7.0",
+        typescript: "^5.7.0",
+        "@types/node": "^24.0.0",
+        vitest: "^3.0.0",
+    };
     const files = {};
     // Root files
     files["package.json"] =
@@ -77,16 +82,21 @@ export function generateMonolithFiles(options) {
             private: true,
             type: "module",
             license: "MIT",
+            zudojs: {
+                projectType: "backend",
+                architecture: "monolith",
+                features: [],
+            },
             scripts: {
-                dev: "node --import tsx watch src/server.ts",
+                dev: "tsx watch src/server.ts",
                 start: "node dist/server.js",
                 build: "tsc",
                 typecheck: "tsc --noEmit",
                 test: "vitest run",
                 lint: "tsc --noEmit",
             },
-            dependencies: Object.fromEntries([...new Set(deps)].map((d) => [d, "workspace:*"])),
-            devDependencies: Object.fromEntries(devDeps.map((d) => [d, "^1.0.0"])),
+            dependencies: Object.fromEntries([...new Set(deps)].map((d) => [d, ZUDOJS_PACKAGES_VERSION])),
+            devDependencies: devDeps,
         }, null, 2) + "\n";
     // tsconfig
     files["tsconfig.json"] = `{
@@ -94,9 +104,9 @@ export function generateMonolithFiles(options) {
     "target": "ES2024",
     "module": "Node16",
     "moduleResolution": "Node16",
-    "allowImportingTsExtensions": true,
+    "outDir": "dist",
+    "rootDir": "src",
     "strict": true,
-    "noEmit": true,
     "skipLibCheck": true,
     "esModuleInterop": true,
     "resolveJsonModule": true,
@@ -107,6 +117,9 @@ export function generateMonolithFiles(options) {
   "exclude": ["node_modules", "dist", "**/*.test.ts"]
 }
 `;
+    if (options.packageManager === "pnpm") {
+        files["pnpm-workspace.yaml"] = renderPnpmWorkspaceFile();
+    }
     // Environment
     files[".env.example"] = `NODE_ENV=development
 PORT=3000
@@ -127,7 +140,7 @@ A Zudojs framework application.
 ## Getting Started
 
 \`\`\`bash
-${options.packageManager === "npm" ? "<SECRET_3ff5e0e0> run dev" : options.packageManager === "yarn" ? "yarn dev" : options.packageManager === "bun" ? "bun run dev" : "pnpm run dev"}
+${options.packageManager === "npm" ? "npm run dev" : options.packageManager === "yarn" ? "yarn dev" : options.packageManager === "bun" ? "bun run dev" : "pnpm run dev"}
 \`\`\`
 
 ## Structure
@@ -150,6 +163,7 @@ src/
 ├── loggers/         # Logger configuration
 ├── middlewares/     # HTTP middleware
 ├── models/          # Data models
+├── modules/         # Runtime modules
 ├── repositories/    # Data repositories
 ├── routes/          # HTTP routes
 ├── services/        # Application services
@@ -165,47 +179,24 @@ MIT
     // src/ entry points
     files["src/index.ts"] = `export { createApp } from "./app.js";
 `;
-    files["src/server.ts"] = `import { createApp } from "./app.js";
-import { createRuntime } from "@zudojs/runtime";
-import { logger } from "@zudojs/logger";
-
-const app = await createApp();
-
-const runtime = createRuntime({
-  onShutdown: async () => {
-    await app.stop();
-  },
-});
-
-await runtime.start();
-
-const server = await app.listen();
-
-process.on("SIGTERM", async () => {
-  await runtime.stop();
-  process.exit(0);
-});
-`;
-    files["src/app.ts"] = `import { logger } from "@zudojs/logger";
-import { createContainer } from "@zudojs/container";
-
-export async function createApp() {
-  const log = logger.child({ service: "app" });
-  const container = createContainer();
-
-  log.info("${nameSlug} v0.1.0 starting...");
-
-  return {
-    container,
-    listen: async () => {
-      log.info("Server started");
-    },
-    stop: async () => {
-      log.info("Shutting down...");
-    },
-  };
-}
-`;
+    files["src/server.ts"] = renderServerFile();
+    // Normalized: the name becomes a file path segment and a class name.
+    const moduleName = normalizeName(options.services[0] ?? "app") || "app";
+    const serviceClassName = `${toPascalCase(moduleName)}Service`;
+    const appModule = moduleSpec(moduleName, "./modules/index.js");
+    files["src/app.ts"] = renderAppFile({
+        applicationName: nameSlug,
+        modules: [appModule],
+    });
+    files[`src/modules/${moduleName}.module.ts`] = renderModuleFile({
+        module: appModule,
+        service: {
+            className: serviceClassName,
+            importPath: "../services/index.js",
+        },
+    });
+    files["src/modules/index.ts"] =
+        `export { ${appModule.className} } from "./${moduleName}.module.js";\n`;
     // Shared directories with empty index.ts
     const sharedDirs = [
         "configs",
@@ -232,23 +223,9 @@ export async function createApp() {
         files[`src/${dir}/index.ts`] = "";
     }
     // Services
-    const serviceName = options.services[0] ?? "app";
-    const serviceNamePascal = serviceName
-        .replace(/-([a-z])/g, (_m, c) => c.toUpperCase())
-        .replace(/^./, (c) => c.toUpperCase());
-    files[`src/services/${serviceName}.service.ts`] = `import { createLogger } from "@zudojs/logger";
-
-export class ${serviceNamePascal}Service {
-  private readonly logger = createLogger({ service: "${serviceName}" });
-
-  async initialize(): Promise<void> {
-    this.logger.info("${serviceName} service initialized");
-  }
-}
-`;
+    files[`src/services/${moduleName}.service.ts`] = renderServiceFile(moduleName);
     files["src/services/index.ts"] =
-        `export { ${serviceNamePascal}Service } from "./${serviceName}.service.js";
-`;
+        `export { ${serviceClassName} } from "./${moduleName}.service.js";\n`;
     // Controllers
     files["src/controllers/health.controller.ts"] =
         `export class HealthController {

package/dist/src/templates/shared/appRuntime.template.d.ts

@@ -0,0 +1,60 @@
+/**
+ * zudojs-cli — Shared Runtime App Templates
+ *
+ * Every architecture template assembles the same four framework pieces:
+ * a logger, a container, an event bus and a set of modules, handed to
+ * `createRuntime(dependencies, options)`.
+ *
+ * The emitted source is kept here rather than duplicated per architecture
+ * so it can be verified against the real `@zudojs/*` packages in one place.
+ * `tests/generatedProject.typecheck.test.ts` type-checks the output of every
+ * template against `packages/<name>/src/index.ts`, so any drift between these
+ * snippets and the framework API fails the CLI test suite.
+ */
+/** Packages every generated runtime entry point imports from. */
+export declare const RUNTIME_APP_DEPENDENCIES: readonly ["@zudojs/core", "@zudojs/runtime", "@zudojs/container", "@zudojs/events", "@zudojs/logger", "@zudojs/constants"];
+/** A module registered with the runtime by the generated `createApp`. */
+export interface RuntimeModuleSpec {
+    /** Slug used for the module id, file name and log messages. */
+    readonly name: string;
+    /** PascalCase class name. */
+    readonly className: string;
+    /** Import specifier the module class is imported from, relative to app.ts. */
+    readonly importPath: string;
+}
+/** Builds a module spec from a raw name. */
+export declare function moduleSpec(name: string, importPath: string): RuntimeModuleSpec;
+/**
+ * Renders `src/app.ts`: assembles the runtime dependencies and returns a
+ * started-on-demand `Runtime`.
+ */
+export declare function renderAppFile(options: {
+    readonly applicationName: string;
+    readonly modules: readonly RuntimeModuleSpec[];
+    /**
+     * Port this app is deployed on. Recorded as runtime metadata so the value
+     * in docker-compose.yml and the Dockerfile is also visible from the app.
+     */
+    readonly port?: number;
+}): string;
+/**
+ * Renders `src/server.ts`: the process entry point. Starts the runtime and
+ * stops it cleanly on SIGINT/SIGTERM.
+ */
+export declare function renderServerFile(appImportPath?: string): string;
+/**
+ * Renders a module class extending `BaseModule`.
+ *
+ * `BaseModule`'s constructor is protected, so the generated class declares a
+ * public constructor — without one the class cannot be instantiated.
+ */
+export declare function renderModuleFile(options: {
+    readonly module: RuntimeModuleSpec;
+    readonly service?: {
+        readonly className: string;
+        readonly importPath: string;
+    };
+}): string;
+/** Renders a service class using the real `createLogger` factory. */
+export declare function renderServiceFile(name: string): string;
+//# sourceMappingURL=appRuntime.template.d.ts.map

package/dist/src/templates/shared/appRuntime.template.js

@@ -0,0 +1,189 @@
+/**
+ * zudojs-cli — Shared Runtime App Templates
+ *
+ * Every architecture template assembles the same four framework pieces:
+ * a logger, a container, an event bus and a set of modules, handed to
+ * `createRuntime(dependencies, options)`.
+ *
+ * The emitted source is kept here rather than duplicated per architecture
+ * so it can be verified against the real `@zudojs/*` packages in one place.
+ * `tests/generatedProject.typecheck.test.ts` type-checks the output of every
+ * template against `packages/<name>/src/index.ts`, so any drift between these
+ * snippets and the framework API fails the CLI test suite.
+ */
+import { toPascalCase } from "../../utils/utils.name.js";
+/** Packages every generated runtime entry point imports from. */
+export const RUNTIME_APP_DEPENDENCIES = [
+    "@zudojs/core",
+    "@zudojs/runtime",
+    "@zudojs/container",
+    "@zudojs/events",
+    "@zudojs/logger",
+    "@zudojs/constants",
+];
+/** Builds a module spec from a raw name. */
+export function moduleSpec(name, importPath) {
+    return {
+        name,
+        className: `${toPascalCase(name)}Module`,
+        importPath,
+    };
+}
+/** Emits a string as a TypeScript string literal that cannot break out. */
+function literal(value) {
+    return JSON.stringify(value);
+}
+/**
+ * Renders `src/app.ts`: assembles the runtime dependencies and returns a
+ * started-on-demand `Runtime`.
+ */
+export function renderAppFile(options) {
+    const imports = [...options.modules]
+        .map((m) => `import { ${m.className} } from ${literal(m.importPath)};`)
+        .join("\n");
+    // An empty array literal would make the loop variable `never`, so the
+    // registration loop is only emitted when there is at least one module.
+    const registration = options.modules.length > 0
+        ? `  for (const module of [
+${options.modules.map((m) => `    new ${m.className}(),`).join("\n")}
+  ]) {
+    modules.set(module.id, module);
+  }
+`
+        : "";
+    const metadata = options.port === undefined
+        ? ""
+        : `\n      metadata: { port: ${options.port} },`;
+    return `import type { Environment } from "@zudojs/constants";
+import { createContainer } from "@zudojs/container";
+import type { Module } from "@zudojs/core";
+import { createEventBus } from "@zudojs/events";
+import { createLogger } from "@zudojs/logger";
+import { createRuntime, type Runtime } from "@zudojs/runtime";
+${imports}
+
+const ENVIRONMENTS: readonly Environment[] = [
+  "development",
+  "test",
+  "staging",
+  "production",
+];
+
+/** Narrows NODE_ENV to a framework Environment without an unchecked cast. */
+function resolveEnvironment(): Environment {
+  const value = process.env["NODE_ENV"];
+  return ENVIRONMENTS.find((candidate) => candidate === value) ?? "development";
+}
+
+/**
+ * Assembles the application runtime.
+ *
+ * \`createRuntime\` takes two arguments: the dependencies the runtime and its
+ * modules share, and the options describing this application.
+ */
+export function createApp(): Runtime {
+  const logger = createLogger({ name: ${literal(options.applicationName)} });
+  const container = createContainer();
+  const eventBus = createEventBus();
+
+  const modules = new Map<string, Module>();
+${registration}
+  const runtime = createRuntime(
+    { modules, logger, container, eventBus },
+    {
+      applicationName: ${literal(options.applicationName)},
+      applicationVersion: "0.1.0",
+      environment: resolveEnvironment(),
+      // Signals are handled explicitly in server.ts.
+      handleSignals: false,${metadata}
+    },
+  );
+
+  runtime.registerReadinessCheck("modules", () => runtime.state === "running");
+
+  return runtime;
+}
+`;
+}
+/**
+ * Renders `src/server.ts`: the process entry point. Starts the runtime and
+ * stops it cleanly on SIGINT/SIGTERM.
+ */
+export function renderServerFile(appImportPath = "./app.js") {
+    return `import { createApp } from ${literal(appImportPath)};
+
+const runtime = createApp();
+
+await runtime.start();
+
+for (const signal of ["SIGINT", "SIGTERM"] as const) {
+  process.once(signal, () => {
+    void runtime
+      .stop()
+      .then(() => {
+        process.exit(0);
+      })
+      .catch((error: unknown) => {
+        console.error(error);
+        process.exit(1);
+      });
+  });
+}
+`;
+}
+/**
+ * Renders a module class extending `BaseModule`.
+ *
+ * `BaseModule`'s constructor is protected, so the generated class declares a
+ * public constructor — without one the class cannot be instantiated.
+ */
+export function renderModuleFile(options) {
+    const { module, service } = options;
+    const serviceImport = service
+        ? `import { ${service.className} } from ${literal(service.importPath)};\n`
+        : "";
+    const serviceField = service
+        ? `  private readonly service = new ${service.className}();\n\n`
+        : "";
+    const serviceInit = service ? "    await this.service.initialize();\n" : "";
+    return `import { BaseModule, type ModuleContext } from "@zudojs/core";
+${serviceImport}
+/**
+ * ${module.name} module.
+ *
+ * Registered with the runtime in app.ts. The runtime calls onInitialize
+ * during start and onShutdown during stop.
+ */
+export class ${module.className} extends BaseModule {
+  public readonly id = ${literal(module.name)};
+  public readonly name = ${literal(module.name)};
+
+${serviceField}  public constructor() {
+    super({ version: "0.1.0" });
+  }
+
+  public override async onInitialize(context: ModuleContext): Promise<void> {
+${serviceInit}    context.logger.info(${literal(`${module.name} module initialized`)});
+  }
+
+  public override async onShutdown(context: ModuleContext): Promise<void> {
+    context.logger.info(${literal(`${module.name} module stopped`)});
+  }
+}
+`;
+}
+/** Renders a service class using the real `createLogger` factory. */
+export function renderServiceFile(name) {
+    const className = `${toPascalCase(name)}Service`;
+    return `import { createLogger } from "@zudojs/logger";
+
+export class ${className} {
+  private readonly logger = createLogger({ name: ${literal(`${name}-service`)} });
+
+  public async initialize(): Promise<void> {
+    this.logger.info(${literal(`${name} service initialized`)});
+  }
+}
+`;
+}
+//# sourceMappingURL=appRuntime.template.js.map

package/dist/src/templates/shared/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * zudojs-cli — Shared Template Fragments
+ */
+export * from "./appRuntime.template.js";
+export * from "./pnpm.template.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/templates/shared/index.js

@@ -0,0 +1,6 @@
+/**
+ * zudojs-cli — Shared Template Fragments
+ */
+export * from "./appRuntime.template.js";
+export * from "./pnpm.template.js";
+//# sourceMappingURL=index.js.map

package/dist/src/templates/shared/pnpm.template.d.ts

@@ -0,0 +1,27 @@
+/**
+ * zudojs-cli — pnpm settings for generated projects
+ *
+ * pnpm 10 stopped running the install scripts of dependencies unless the
+ * project lists them, and pnpm 11 turned the resulting notice into a failing
+ * `ERR_PNPM_IGNORED_BUILDS`. Every generated project depends on `tsx`
+ * (backend) or Vite (frontend), both of which pull in esbuild and its
+ * postinstall, so a fresh `pnpm install` exited with code 1 and
+ * `pnpm run dev` — which re-verifies the install first — never started.
+ *
+ * pnpm 10 reads `onlyBuiltDependencies`; pnpm 11 reads `allowBuilds`. Both
+ * are written so either version installs cleanly, and both live in
+ * `pnpm-workspace.yaml`, the file pnpm itself creates for this purpose.
+ *
+ * @module templates/shared/pnpm
+ */
+/** Dependencies whose install scripts a generated project allows. */
+export declare const PNPM_ALLOWED_BUILD_SCRIPTS: readonly ["esbuild", "@swc/core", "sharp", "@parcel/watcher", "@tailwindcss/oxide", "unrs-resolver"];
+/**
+ * Renders `pnpm-workspace.yaml`.
+ *
+ * `packages` is omitted for a single-package project: pnpm then treats the
+ * directory as the sole workspace member, which is what it already does
+ * when it writes the file itself.
+ */
+export declare function renderPnpmWorkspaceFile(packages?: readonly string[]): string;
+//# sourceMappingURL=pnpm.template.d.ts.map

package/dist/src/templates/shared/pnpm.template.js

@@ -0,0 +1,57 @@
+/**
+ * zudojs-cli — pnpm settings for generated projects
+ *
+ * pnpm 10 stopped running the install scripts of dependencies unless the
+ * project lists them, and pnpm 11 turned the resulting notice into a failing
+ * `ERR_PNPM_IGNORED_BUILDS`. Every generated project depends on `tsx`
+ * (backend) or Vite (frontend), both of which pull in esbuild and its
+ * postinstall, so a fresh `pnpm install` exited with code 1 and
+ * `pnpm run dev` — which re-verifies the install first — never started.
+ *
+ * pnpm 10 reads `onlyBuiltDependencies`; pnpm 11 reads `allowBuilds`. Both
+ * are written so either version installs cleanly, and both live in
+ * `pnpm-workspace.yaml`, the file pnpm itself creates for this purpose.
+ *
+ * @module templates/shared/pnpm
+ */
+/** Dependencies whose install scripts a generated project allows. */
+export const PNPM_ALLOWED_BUILD_SCRIPTS = [
+    "esbuild",
+    "@swc/core",
+    "sharp",
+    "@parcel/watcher",
+    "@tailwindcss/oxide",
+    "unrs-resolver",
+];
+/**
+ * Renders `pnpm-workspace.yaml`.
+ *
+ * `packages` is omitted for a single-package project: pnpm then treats the
+ * directory as the sole workspace member, which is what it already does
+ * when it writes the file itself.
+ */
+export function renderPnpmWorkspaceFile(packages = []) {
+    const lines = [];
+    if (packages.length > 0) {
+        lines.push("packages:");
+        for (const glob of packages) {
+            lines.push(`  - ${JSON.stringify(glob)}`);
+        }
+        lines.push("");
+    }
+    lines.push("# Dependencies allowed to run install scripts (pnpm 10).");
+    lines.push("onlyBuiltDependencies:");
+    for (const name of PNPM_ALLOWED_BUILD_SCRIPTS) {
+        // Quoted: a bare leading "@" is a reserved YAML indicator.
+        lines.push(`  - ${JSON.stringify(name)}`);
+    }
+    lines.push("");
+    lines.push("# The same list in the form pnpm 11 reads.");
+    lines.push("allowBuilds:");
+    for (const name of PNPM_ALLOWED_BUILD_SCRIPTS) {
+        lines.push(`  ${JSON.stringify(name)}: true`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+//# sourceMappingURL=pnpm.template.js.map

package/dist/src/utils/index.d.ts

@@ -3,8 +3,8 @@
  *
  * Shared utility functions for the CLI scaffolding system.
  */
-export { writeFile, writeFileTree } from "./utils.fileSystem.js";
-export { normalizeName } from "./utils.name.js";
+export { writeFile, writeFileTree, mergeBarrelExport, } from "./utils.fileSystem.js";
+export { normalizeName, toPascalCase, toCamelCase } from "./utils.name.js";
 export { detectArchitecture } from "./utils.detect.js";
-export { execCommand } from "./utils.exec.js";
+export { execCommand, runStreaming } from "./utils.exec.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/utils/index.js

@@ -3,8 +3,8 @@
  *
  * Shared utility functions for the CLI scaffolding system.
  */
-export { writeFile, writeFileTree } from "./utils.fileSystem.js";
-export { normalizeName } from "./utils.name.js";
+export { writeFile, writeFileTree, mergeBarrelExport, } from "./utils.fileSystem.js";
+export { normalizeName, toPascalCase, toCamelCase } from "./utils.name.js";
 export { detectArchitecture } from "./utils.detect.js";
-export { execCommand } from "./utils.exec.js";
+export { execCommand, runStreaming } from "./utils.exec.js";
 //# sourceMappingURL=index.js.map

package/dist/src/utils/utils.detect.d.ts

@@ -1,2 +1,11 @@
+/**
+ * Returns the recorded architecture of the project at `cwd`, or `null` when
+ * the directory is not a Zudojs project.
+ *
+ * Used to read a `zudojs.config.json` that no template has ever written, so
+ * it returned `null` for every project. It now reads the same sources as
+ * every other command: the manifest, the legacy `zudojs.config.ts`, then
+ * the `zudojs` block in `package.json`.
+ */
 export declare function detectArchitecture(cwd: string): Promise<string | null>;
 //# sourceMappingURL=utils.detect.d.ts.map

package/dist/src/utils/utils.detect.js

@@ -1,14 +1,14 @@
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { resolveProjectLayout } from "../resolvers/layout/projectLayout.core.js";
+/**
+ * Returns the recorded architecture of the project at `cwd`, or `null` when
+ * the directory is not a Zudojs project.
+ *
+ * Used to read a `zudojs.config.json` that no template has ever written, so
+ * it returned `null` for every project. It now reads the same sources as
+ * every other command: the manifest, the legacy `zudojs.config.ts`, then
+ * the `zudojs` block in `package.json`.
+ */
 export async function detectArchitecture(cwd) {
-    try {
-        const configPath = join(cwd, "zudojs.config.json");
-        const content = await readFile(configPath, "utf-8");
-        const config = JSON.parse(content);
-        return config.architecture ?? null;
-    }
-    catch {
-        return null;
-    }
+    return resolveProjectLayout(cwd)?.architecture ?? null;
 }
 //# sourceMappingURL=utils.detect.js.map

package/dist/src/utils/utils.exec.d.ts

@@ -2,5 +2,39 @@ export interface ExecResult {
     readonly stdout: string;
     readonly stderr: string;
 }
-export declare function execCommand(file: string, args: readonly string[], cwd: string): Promise<ExecResult>;
+export interface ExecOptions {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly timeout?: number;
+    /** Aborting the signal terminates the child process. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Quotes one argument for cmd.exe. Arguments are validated before they reach
+ * here (project and service names are `[A-Za-z0-9_-]`), so this is defence
+ * in depth rather than the only barrier.
+ */
+export declare function quoteForWindowsShell(argument: string): string;
+/** The spawn arguments and shell flag a command needs on this platform. */
+export declare function resolveSpawnTarget(file: string, args: readonly string[], platform?: NodeJS.Platform): {
+    readonly file: string;
+    readonly args: string[];
+    readonly shell: boolean;
+};
+/**
+ * Runs a short-lived command and buffers its output.
+ *
+ * Suitable for quick probes (version checks, git commands). Do NOT use this
+ * for long-running processes such as dev servers or dependency installs —
+ * use {@link runStreaming} instead.
+ */
+export declare function execCommand(file: string, args: readonly string[], cwd: string, options?: ExecOptions): Promise<ExecResult>;
+/**
+ * Runs a command with inherited stdio and no timeout.
+ *
+ * Use for long-running processes (dev servers) and for dependency installs
+ * so output streams to the user and slow commands are not killed. Pass a
+ * `signal` to stop the process from the outside; an aborted run resolves
+ * rather than rejects, since stopping it was the caller's intent.
+ */
+export declare function runStreaming(file: string, args: readonly string[], cwd: string, options?: ExecOptions): Promise<void>;
 //# sourceMappingURL=utils.exec.d.ts.map