zudojs-cli 1.2.1 → 2.0.0

package/dist/src/scaffolders/scaffolder.helper.d.ts

@@ -9,5 +9,15 @@ export interface ScaffolderOptions {
     readonly targetPath: string;
     readonly fallbackFiles: Record<string, string>;
 }
+/**
+ * Timeout for an official framework scaffolder, in milliseconds.
+ *
+ * `npm create vite@latest` and `npx create-next-app@latest` download a
+ * package tree from the registry, which routinely takes several minutes on
+ * a cold cache or a slow link. The 2-minute default of `execCommand` killed
+ * them mid-download and the user silently received the built-in fallback
+ * template instead of the real framework scaffold.
+ */
+export declare const SCAFFOLD_TIMEOUT_MS = 900000;
 export declare function scaffoldWithFallback(options: ScaffolderOptions): Promise<boolean>;
 //# sourceMappingURL=scaffolder.helper.d.ts.map

package/dist/src/scaffolders/scaffolder.helper.js

@@ -5,17 +5,40 @@
  */
 import { execCommand } from "../utils/utils.exec.js";
 import { writeFileTree } from "../utils/utils.fileSystem.js";
+/**
+ * Timeout for an official framework scaffolder, in milliseconds.
+ *
+ * `npm create vite@latest` and `npx create-next-app@latest` download a
+ * package tree from the registry, which routinely takes several minutes on
+ * a cold cache or a slow link. The 2-minute default of `execCommand` killed
+ * them mid-download and the user silently received the built-in fallback
+ * template instead of the real framework scaffold.
+ */
+export const SCAFFOLD_TIMEOUT_MS = 900000;
+/** Describes why a scaffolder failed, including the child's own stderr. */
+function describeFailure(error) {
+    if (!(error instanceof Error))
+        return String(error);
+    const killed = error.killed === true;
+    const signal = error.signal;
+    const stderr = error.stderr;
+    const detail = typeof stderr === "string" ? stderr.trim() : "";
+    const headline = killed && (signal === "SIGTERM" || signal === null || signal === undefined)
+        ? `timed out after ${Math.round(SCAFFOLD_TIMEOUT_MS / 1000)}s`
+        : `failed: ${error.message.split("\n")[0]}`;
+    return detail ? `${headline}; ${detail}` : headline;
+}
 export async function scaffoldWithFallback(options) {
     try {
         await execCommand(options.command, Array.from(options.args), options.targetPath, {
             // Suppress interactive prompts from create-* tools.
             env: { ...process.env, CI: "1" },
+            timeout: SCAFFOLD_TIMEOUT_MS,
         });
         return true;
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        console.warn(`Warning: official scaffolder "${options.command} ${options.args.join(" ")}" failed (${message.split("\n")[0]}). Using built-in fallback template.`);
+        console.warn(`Warning: official scaffolder "${options.command} ${options.args.join(" ")}" ${describeFailure(error)}. Using built-in fallback template.`);
         await writeFileTree(options.targetPath, options.fallbackFiles);
         return false;
     }

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

@@ -1,5 +1,5 @@
 /**
  * zudojs-cli — Microservice Template Index
  */
-export { generateMicroserviceFiles, resolveMicroserviceServices, DEFAULT_MICROSERVICE_SERVICES, RESERVED_MICROSERVICE_APP_NAMES, } from "./microservice.template.js";
+export { generateMicroserviceFiles, resolveMicroserviceServices, RESERVED_MICROSERVICE_APP_NAMES, } from "./microservice.template.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1,5 +1,5 @@
 /**
  * zudojs-cli — Microservice Template Index
  */
-export { generateMicroserviceFiles, resolveMicroserviceServices, DEFAULT_MICROSERVICE_SERVICES, RESERVED_MICROSERVICE_APP_NAMES, } from "./microservice.template.js";
+export { generateMicroserviceFiles, resolveMicroserviceServices, RESERVED_MICROSERVICE_APP_NAMES, } from "./microservice.template.js";
 //# sourceMappingURL=index.js.map

package/dist/src/templates/microservice/microservice.template.d.ts

@@ -22,8 +22,6 @@
  * ```
  */
 import type { ScaffoldOptions } from "../../types/index.js";
-/** Default service names used when none are provided. */
-export declare const DEFAULT_MICROSERVICE_SERVICES: readonly ["identity", "enrollment", "assessment", "notification"];
 /**
  * The gateway app is always generated at `apps/gateway`, so "gateway" is a
  * reserved name: a service called `gateway` would produce a second, competing
@@ -32,8 +30,14 @@ export declare const DEFAULT_MICROSERVICE_SERVICES: readonly ["identity", "enrol
 export declare const RESERVED_MICROSERVICE_APP_NAMES: readonly ["gateway"];
 /**
  * Normalizes a requested service list into the service apps generated under
- * `apps/services/`. Reserved names and duplicates are dropped; an empty list
- * falls back to DEFAULT_MICROSERVICE_SERVICES.
+ * `apps/services/`. Reserved names and duplicates are dropped.
+ *
+ * An empty request yields an empty list: a new project gets the gateway and
+ * nothing else. This used to substitute four example names
+ * (`identity`, `enrollment`, `assessment`, `notification`), which put four
+ * domains nobody asked for into every microservice project and left the
+ * author deleting them before they could start. Services are created when
+ * they are named — here, or later with `zudojs generate service <name>`.
  */
 export declare function resolveMicroserviceServices(requested: readonly string[]): readonly string[];
 export declare function generateMicroserviceFiles(options: ScaffoldOptions): Record<string, string>;

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

@@ -23,14 +23,7 @@
  */
 import { ZUDOJS_PACKAGES_VERSION } from "../../constants/index.js";
 import { normalizeName } from "../../utils/utils.name.js";
-import { RUNTIME_APP_DEPENDENCIES, moduleSpec, renderAppPackageDockerfile, renderAppFile, renderModuleFile, renderServerFile, renderPnpmWorkspaceFile, } from "../shared/index.js";
-/** Default service names used when none are provided. */
-export const DEFAULT_MICROSERVICE_SERVICES = [
-    "identity",
-    "enrollment",
-    "assessment",
-    "notification",
-];
+import { RUNTIME_APP_DEPENDENCIES, capabilityPackages, moduleSpec, renderAppPackageDockerfile, renderAppFile, renderModuleFile, renderServerFile, renderPnpmWorkspaceFile, resolveProjectCapabilities, } from "../shared/index.js";
 /**
  * The gateway app is always generated at `apps/gateway`, so "gateway" is a
  * reserved name: a service called `gateway` would produce a second, competing
@@ -39,22 +32,32 @@ export const DEFAULT_MICROSERVICE_SERVICES = [
 export const RESERVED_MICROSERVICE_APP_NAMES = ["gateway"];
 /**
  * Normalizes a requested service list into the service apps generated under
- * `apps/services/`. Reserved names and duplicates are dropped; an empty list
- * falls back to DEFAULT_MICROSERVICE_SERVICES.
+ * `apps/services/`. Reserved names and duplicates are dropped.
+ *
+ * An empty request yields an empty list: a new project gets the gateway and
+ * nothing else. This used to substitute four example names
+ * (`identity`, `enrollment`, `assessment`, `notification`), which put four
+ * domains nobody asked for into every microservice project and left the
+ * author deleting them before they could start. Services are created when
+ * they are named — here, or later with `zudojs generate service <name>`.
  */
 export function resolveMicroserviceServices(requested) {
     const normalized = requested
         .map((service) => normalizeName(service))
         .filter((service) => service.length > 0 &&
         !RESERVED_MICROSERVICE_APP_NAMES.some((reserved) => reserved === service));
-    const unique = [...new Set(normalized)];
-    return unique.length > 0 ? unique : [...DEFAULT_MICROSERVICE_SERVICES];
+    return [...new Set(normalized)];
 }
 export function generateMicroserviceFiles(options) {
     const nameSlug = options.projectName
         .replace(/[^a-z0-9-]+/gi, "-")
         .toLowerCase();
     const services = resolveMicroserviceServices(options.services);
+    // The workspace root records the capabilities for the project as a whole
+    // (`zudojs info` reads it when there is no manifest); the service apps
+    // record them next to the dependencies that back them, which is where
+    // `zudojs add` writes and `zudojs doctor` reads.
+    const capabilities = resolveProjectCapabilities(options);
     const files = {};
     // Root package.json (workspace root)
     const rootScripts = {
@@ -91,7 +94,7 @@ export function generateMicroserviceFiles(options) {
             zudojs: {
                 projectType: "backend",
                 architecture: "microservice",
-                features: [],
+                features: capabilities,
             },
             ...(options.packageManager === "pnpm"
                 ? {}
@@ -152,7 +155,14 @@ A microservice architecture built with the Zudojs framework.
 ## Services
 
 - **gateway** - Port 3000
-${services.map((s, i) => `- **${s}** - Port ${3001 + i}`).join("\n")}
+${services.length > 0
+        ? services.map((s, i) => `- **${s}** - Port ${3001 + i}`).join("\n")
+        : `
+No services yet. Add one with:
+
+\`\`\`bash
+npx zudojs generate service <name>
+\`\`\``}
 
 ## Getting Started
 
@@ -171,8 +181,10 @@ docker-compose up
 
 MIT
 `;
-    // Shared types
-    files["src/types/index.ts"] = ``;
+    // No `src/` at the workspace root: there is no package.json, tsconfig or
+    // app there, so nothing would compile a file placed in it. Every app owns
+    // its own `src/types/`, and code genuinely shared between apps belongs in a
+    // workspace package the author creates deliberately.
     const appTsconfig = `{
   "compilerOptions": {
     "target": "ES2024",
@@ -242,10 +254,8 @@ MIT
         "@zudojs/config",
         "@zudojs/errors",
         "@zudojs/http",
+        ...capabilityPackages(capabilities),
     ];
-    if (options.enableCQRS) {
-        serviceDeps.push("@zudojs/cqrs");
-    }
     for (const svc of services) {
         const svcName = svc;
         const svcIndex = services.indexOf(svcName);
@@ -256,6 +266,7 @@ MIT
                 version: "0.1.0",
                 private: true,
                 type: "module",
+                zudojs: { features: capabilities },
                 scripts: {
                     dev: "tsx watch src/server.ts",
                     start: "node dist/server.js",

package/dist/src/templates/modular-monolith/modularMonolith.template.js

@@ -34,17 +34,25 @@
 import { renderDatabaseEnv } from "../../adapters/databases/databaseAdapter.resolver.js";
 import { ZUDOJS_PACKAGES_VERSION } from "../../constants/index.js";
 import { normalizeName } from "../../utils/utils.name.js";
-import { RUNTIME_APP_DEPENDENCIES, moduleSpec, renderAppFile, renderModuleFile, renderServerFile, renderPnpmWorkspaceFile, } from "../shared/index.js";
+import { RUNTIME_APP_DEPENDENCIES, capabilityPackages, moduleSpec, renderAppFile, renderModuleFile, renderServerFile, renderPnpmWorkspaceFile, resolveProjectCapabilities, } from "../shared/index.js";
 export function generateModularMonolithFiles(options) {
     const nameSlug = options.projectName
         .replace(/[^a-z0-9-]+/gi, "-")
         .toLowerCase();
     // Normalized: each name becomes a directory segment and a class name.
-    const modules = (options.services.length > 0
-        ? options.services
-        : ["identity", "enrollment", "assessment"])
+    //
+    // An empty list generates no modules. This used to substitute three example
+    // names (`identity`, `enrollment`, `assessment`), so every modular monolith
+    // arrived with three domains nobody asked for. Modules are created when they
+    // are named — with `--services`, or later with `zudojs generate module <name>`.
+    const modules = options.services
         .map((m) => normalizeName(m))
         .filter((m) => m.length > 0);
+    // Recorded in package.json and backed by the packages below, so the
+    // `zudojs doctor` feature check has something real to verify. The
+    // architecture's own CQRS structure means cqrs/messaging are always
+    // installed, whether or not they were requested as capabilities.
+    const capabilities = resolveProjectCapabilities(options);
     const deps = [
         ...RUNTIME_APP_DEPENDENCIES,
         "@zudojs/config",
@@ -54,6 +62,7 @@ export function generateModularMonolithFiles(options) {
         "@zudojs/cqrs",
         "@zudojs/messaging",
         "@zudojs/http",
+        ...capabilityPackages(capabilities),
     ];
     const devDeps = {
         tsx: "^4.7.0",
@@ -73,7 +82,7 @@ export function generateModularMonolithFiles(options) {
             zudojs: {
                 projectType: "backend",
                 architecture: "modular-monolith",
-                features: [],
+                features: capabilities,
             },
             scripts: {
                 dev: "tsx watch src/server.ts",
@@ -121,9 +130,17 @@ A modular monolith built with the Zudojs framework.
 
 ## Architecture
 
-This project uses a **modular monolith** architecture with the following modules:
+This project uses a **modular monolith** architecture.
 
-${modules.map((m) => `- **${m}**`).join("\n")}
+${modules.length > 0
+        ? `Modules:
+
+${modules.map((m) => `- **${m}**`).join("\n")}`
+        : `No modules yet. Add one with:
+
+\`\`\`bash
+npx zudojs generate module <name>
+\`\`\``}
 
 ## Getting Started
 
@@ -182,7 +199,9 @@ MIT
         files[`src/modules/${spec.name}/commands/index.ts`] = ``;
         files[`src/modules/${spec.name}/queries/index.ts`] = ``;
     }
-    files["tests/index.ts"] = `import { describe, it, expect } from "vitest";
+    // The name must match vitest's default `include`
+    // (`**/*.{test,spec}.?(c|m)[jt]s?(x)`); `tests/index.ts` did not.
+    files["tests/app.test.ts"] = `import { describe, it, expect } from "vitest";
 
 describe("Application", () => {
   it("should bootstrap correctly", () => {

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

@@ -40,10 +40,13 @@
 import { renderDatabaseEnv } from "../../adapters/databases/databaseAdapter.resolver.js";
 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";
+import { RUNTIME_APP_DEPENDENCIES, capabilityPackages, moduleSpec, renderAppFile, renderModuleFile, renderServerFile, renderServiceFile, renderPnpmWorkspaceFile, resolveProjectCapabilities, } from "../shared/index.js";
 export function generateMonolithFiles(options) {
     const name = options.projectName;
     const nameSlug = name.replace(/[^a-z0-9-]+/gi, "-").toLowerCase();
+    // Recorded in package.json and backed by the packages below, so the
+    // `zudojs doctor` feature check has something real to verify.
+    const capabilities = resolveProjectCapabilities(options);
     const deps = [
         ...RUNTIME_APP_DEPENDENCIES,
         "@zudojs/config",
@@ -52,21 +55,10 @@ export function generateMonolithFiles(options) {
         "@zudojs/validation",
         "@zudojs/schema",
         "@zudojs/http",
+        ...capabilityPackages(capabilities),
     ];
     if (options.enableCQRS) {
-        deps.push("@zudojs/cqrs", "@zudojs/events", "@zudojs/messaging");
-    }
-    if (options.enableDatabase) {
-        deps.push("@zudojs/database");
-    }
-    if (options.enableQueue) {
-        deps.push("@zudojs/queue");
-    }
-    if (options.enableObservability) {
-        deps.push("@zudojs/observability");
-    }
-    if (options.enableOpenAPI) {
-        deps.push("@zudojs/openapi");
+        deps.push("@zudojs/events");
     }
     const devDeps = {
         tsx: "^4.7.0",
@@ -86,7 +78,7 @@ export function generateMonolithFiles(options) {
             zudojs: {
                 projectType: "backend",
                 architecture: "monolith",
-                features: [],
+                features: capabilities,
             },
             scripts: {
                 dev: "tsx watch src/server.ts",
@@ -240,8 +232,10 @@ MIT
     files["src/controllers/index.ts"] =
         `export { HealthController } from "./health.controller.js";
 `;
-    // Tests
-    files["tests/index.ts"] = `import { describe, it, expect } from "vitest";
+    // Tests. The file name must match vitest's default `include`
+    // (`**/*.{test,spec}.?(c|m)[jt]s?(x)`); `tests/index.ts` did not, so the
+    // generated `test` script exited 1 with "No test files found".
+    files["tests/app.test.ts"] = `import { describe, it, expect } from "vitest";
 
 describe("Application", () => {
   it("should be configured correctly", () => {

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

@@ -0,0 +1,25 @@
+/**
+ * zudojs-cli — Capabilities a generated project declares.
+ *
+ * Every template used to stamp `zudojs.features: []` into the package.json it
+ * wrote, although it had already used the `enable*` flags to choose the
+ * project's dependencies. `zudojs doctor` reads only `pkg.zudojs.features`,
+ * so its check ("every declared feature has its package") passed vacuously in
+ * every project the CLI created, and `zudojs add` was the only thing that
+ * could ever put a value there.
+ *
+ * The list produced here is the same one `zudojs create` records as
+ * `capabilities` in `.zudojs/manifest.json`, and {@link capabilityPackages}
+ * gives the packages that back it, so a declared feature is always installed.
+ */
+import type { ScaffoldOptions } from "../../types/index.js";
+/**
+ * The capability ids a scaffolded project was created with.
+ */
+export declare function resolveProjectCapabilities(options: ScaffoldOptions): readonly string[];
+/**
+ * The `@zudojs/*` packages that back `capabilities`, using the same mapping
+ * `zudojs add` and `zudojs doctor` use.
+ */
+export declare function capabilityPackages(capabilities: readonly string[]): readonly string[];
+//# sourceMappingURL=capability.template.d.ts.map

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

@@ -0,0 +1,46 @@
+/**
+ * zudojs-cli — Capabilities a generated project declares.
+ *
+ * Every template used to stamp `zudojs.features: []` into the package.json it
+ * wrote, although it had already used the `enable*` flags to choose the
+ * project's dependencies. `zudojs doctor` reads only `pkg.zudojs.features`,
+ * so its check ("every declared feature has its package") passed vacuously in
+ * every project the CLI created, and `zudojs add` was the only thing that
+ * could ever put a value there.
+ *
+ * The list produced here is the same one `zudojs create` records as
+ * `capabilities` in `.zudojs/manifest.json`, and {@link capabilityPackages}
+ * gives the packages that back it, so a declared feature is always installed.
+ */
+import { FEATURE_PACKAGES } from "../../constants/index.js";
+/** Capability flags, in the order the manifest records them. */
+const CAPABILITY_FLAGS = [
+    ["cqrs", "enableCQRS"],
+    ["messaging", "enableMessaging"],
+    ["observability", "enableObservability"],
+    ["openapi", "enableOpenAPI"],
+    ["database", "enableDatabase"],
+    ["queue", "enableQueue"],
+];
+/**
+ * The capability ids a scaffolded project was created with.
+ */
+export function resolveProjectCapabilities(options) {
+    return CAPABILITY_FLAGS.filter(([, flag]) => options[flag] === true).map(([capability]) => capability);
+}
+/**
+ * The `@zudojs/*` packages that back `capabilities`, using the same mapping
+ * `zudojs add` and `zudojs doctor` use.
+ */
+export function capabilityPackages(capabilities) {
+    const packages = new Set();
+    for (const capability of capabilities) {
+        for (const name of FEATURE_PACKAGES[capability] ?? [
+            `@zudojs/${capability}`,
+        ]) {
+            packages.add(name);
+        }
+    }
+    return [...packages];
+}
+//# sourceMappingURL=capability.template.js.map

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

@@ -2,6 +2,7 @@
  * zudojs-cli — Shared Template Fragments
  */
 export * from "./appRuntime.template.js";
+export * from "./capability.template.js";
 export * from "./dockerfile.template.js";
 export * from "./pnpm.template.js";
 export * from "./server.template.js";

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

@@ -2,6 +2,7 @@
  * zudojs-cli — Shared Template Fragments
  */
 export * from "./appRuntime.template.js";
+export * from "./capability.template.js";
 export * from "./dockerfile.template.js";
 export * from "./pnpm.template.js";
 export * from "./server.template.js";

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

@@ -12,6 +12,9 @@ export interface ExecOptions {
  * 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.
+ *
+ * @throws {CLIValidationError} If the argument contains `"`, `%` or `!`,
+ *   none of which cmd.exe can be made to treat as literal text.
  */
 export declare function quoteForWindowsShell(argument: string): string;
 /** The spawn arguments and shell flag a command needs on this platform. */
@@ -20,6 +23,25 @@ export declare function resolveSpawnTarget(file: string, args: readonly string[]
     readonly args: string[];
     readonly shell: boolean;
 };
+/**
+ * The environment a child gets, hardened for the Windows shell path.
+ *
+ * `cmd.exe` searches the current directory before `PATH`, so a `pnpm.cmd`
+ * or `npm.bat` committed into a cloned repository would win over the real
+ * package manager. `NoDefaultCurrentDirectoryInExePath` removes the current
+ * directory from that search. It is only meaningful on win32 and only when
+ * a shell is involved; everywhere else the caller's env is passed through
+ * unchanged (POSIX `PATH` lookup never implies the cwd, and `shell` is
+ * false there).
+ */
+export declare function resolveChildEnv(shell: boolean, env: NodeJS.ProcessEnv | undefined, platform?: NodeJS.Platform): NodeJS.ProcessEnv | undefined;
+/**
+ * Default timeout for {@link execCommand}, in milliseconds.
+ *
+ * Sized for quick probes. Anything that downloads from a registry needs an
+ * explicit, much larger timeout — see `SCAFFOLD_TIMEOUT_MS`.
+ */
+export declare const DEFAULT_EXEC_TIMEOUT_MS = 120000;
 /**
  * Runs a short-lived command and buffers its output.
  *

package/dist/src/utils/utils.exec.js

@@ -1,5 +1,6 @@
 import { execFile, spawn } from "node:child_process";
 import { promisify } from "node:util";
+import { CLIValidationError } from "../errors/index.js";
 const execFileAsync = promisify(execFile);
 /**
  * Commands that are `.cmd` shims rather than executables on Windows.
@@ -23,17 +24,35 @@ const WINDOWS_SHIM_COMMANDS = new Set([
 ]);
 /** Characters that need quoting when a command line goes through cmd.exe. */
 const CMD_UNSAFE = /[\s"&|<>^()%!]/;
+/**
+ * Characters that cannot be made safe by quoting on the cmd.exe path.
+ *
+ * `cmd.exe` has no escape character inside a quoted string: it toggles quote
+ * state on every `"`, so an embedded quote ends the string and everything
+ * after it — `&`, `|`, `>` — is parsed as shell syntax. The C-runtime `\"`
+ * escape means nothing to cmd. `%VAR%` and delayed-expansion `!VAR!` are
+ * likewise expanded inside quotes. There is no correct escaping, so an
+ * argument carrying one of these is rejected instead.
+ */
+const CMD_UNQUOTABLE = /["%!]/;
 /**
  * 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.
+ *
+ * @throws {CLIValidationError} If the argument contains `"`, `%` or `!`,
+ *   none of which cmd.exe can be made to treat as literal text.
  */
 export function quoteForWindowsShell(argument) {
+    if (CMD_UNQUOTABLE.test(argument)) {
+        throw new CLIValidationError(`Cannot pass the argument ${JSON.stringify(argument)} to a Windows shell command: ` +
+            `the characters ", % and ! cannot be escaped for cmd.exe. Remove them and try again.`);
+    }
     if (argument.length === 0)
         return '""';
     if (!CMD_UNSAFE.test(argument))
         return argument;
-    return `"${argument.replace(/"/g, '\\"')}"`;
+    return `"${argument}"`;
 }
 /** The spawn arguments and shell flag a command needs on this platform. */
 export function resolveSpawnTarget(file, args, platform = process.platform) {
@@ -46,6 +65,32 @@ export function resolveSpawnTarget(file, args, platform = process.platform) {
     }
     return { file, args: Array.from(args), shell: false };
 }
+/**
+ * The environment a child gets, hardened for the Windows shell path.
+ *
+ * `cmd.exe` searches the current directory before `PATH`, so a `pnpm.cmd`
+ * or `npm.bat` committed into a cloned repository would win over the real
+ * package manager. `NoDefaultCurrentDirectoryInExePath` removes the current
+ * directory from that search. It is only meaningful on win32 and only when
+ * a shell is involved; everywhere else the caller's env is passed through
+ * unchanged (POSIX `PATH` lookup never implies the cwd, and `shell` is
+ * false there).
+ */
+export function resolveChildEnv(shell, env, platform = process.platform) {
+    if (!shell || platform !== "win32")
+        return env;
+    return {
+        ...(env ?? process.env),
+        NoDefaultCurrentDirectoryInExePath: "1",
+    };
+}
+/**
+ * Default timeout for {@link execCommand}, in milliseconds.
+ *
+ * Sized for quick probes. Anything that downloads from a registry needs an
+ * explicit, much larger timeout — see `SCAFFOLD_TIMEOUT_MS`.
+ */
+export const DEFAULT_EXEC_TIMEOUT_MS = 120000;
 /**
  * Runs a short-lived command and buffers its output.
  *
@@ -55,11 +100,12 @@ export function resolveSpawnTarget(file, args, platform = process.platform) {
  */
 export async function execCommand(file, args, cwd, options = {}) {
     const target = resolveSpawnTarget(file, args);
+    const env = resolveChildEnv(target.shell, options.env);
     const { stdout, stderr } = await execFileAsync(target.file, target.args, {
         cwd,
-        timeout: options.timeout ?? 120000,
+        timeout: options.timeout ?? DEFAULT_EXEC_TIMEOUT_MS,
         shell: target.shell,
-        ...(options.env ? { env: options.env } : {}),
+        ...(env ? { env } : {}),
         ...(options.signal ? { signal: options.signal } : {}),
     });
     return { stdout, stderr };
@@ -74,12 +120,13 @@ export async function execCommand(file, args, cwd, options = {}) {
  */
 export function runStreaming(file, args, cwd, options = {}) {
     const target = resolveSpawnTarget(file, args);
+    const env = resolveChildEnv(target.shell, options.env);
     return new Promise((resolve, reject) => {
         const child = spawn(target.file, target.args, {
             cwd,
             stdio: "inherit",
             shell: target.shell,
-            ...(options.env ? { env: options.env } : {}),
+            ...(env ? { env } : {}),
             ...(options.signal ? { signal: options.signal } : {}),
         });
         child.on("error", (error) => {

package/dist/src/utils/utils.fileSystem.js

@@ -1,13 +1,57 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { mkdir, writeFile as writeFileAsync } from "node:fs/promises";
-import { dirname, join, relative } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep, } from "node:path";
 import { activeWriteCapture } from "./utils.writeGuard.js";
+/**
+ * Resolves `path` through symlinks as far as it exists on disk, keeping the
+ * components that do not exist yet verbatim.
+ *
+ * Containment cannot be decided on the literal string alone: `mkdir` with
+ * `recursive: true` is a no-op on an existing directory, so if a component of
+ * the path is a symlink the write follows it to wherever it points. Only the
+ * real path of the deepest existing ancestor answers where the bytes land.
+ */
+function realizePath(path) {
+    const absolute = resolve(path);
+    const tail = [];
+    let current = absolute;
+    for (;;) {
+        try {
+            const real = realpathSync(current);
+            return tail.length === 0 ? real : join(real, ...tail);
+        }
+        catch {
+            const parent = dirname(current);
+            // Reached the filesystem root without finding anything that exists.
+            if (parent === current)
+                return absolute;
+            tail.unshift(basename(current));
+            current = parent;
+        }
+    }
+}
+/** Whether `target` is `base` itself or lives underneath it. */
+function isContained(base, target) {
+    if (base === target)
+        return true;
+    const relativePath = relative(base, target);
+    return (relativePath !== "" &&
+        !isAbsolute(relativePath) &&
+        !relativePath.startsWith(`..${sep}`) &&
+        relativePath !== "..");
+}
 function assertSafePath(basePath, filePath) {
     const resolved = join(basePath, filePath);
     const relativePath = relative(basePath, resolved);
     if (relativePath.startsWith("..") || relativePath.includes("..")) {
         throw new Error(`Path traversal detected: ${filePath}`);
     }
+    // Re-assert containment against what is actually on disk, so a symlinked
+    // directory inside the project cannot carry the write outside it.
+    if (!isContained(realizePath(basePath), realizePath(resolved))) {
+        throw new Error(`Path escapes the project through a symlink: ${filePath}. ` +
+            `Replace the symlinked directory with a real one, or generate into a different path.`);
+    }
 }
 export async function writeFile(basePath, filePath, content) {
     assertSafePath(basePath, filePath);

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

@@ -15,6 +15,15 @@ export declare const SAFE_PATH_SEGMENT: RegExp;
  * `normalizeName` strips everything outside `[a-z0-9-]`, so a name such as
  * `"..."` or `"!!!"` collapses to the empty string and the generator writes
  * `src//.event.ts` with an anonymous exported class. Reject it up front.
+ *
+ * A name whose normalized form starts with a digit (`2fa`, `401-handler`) is
+ * rejected for the same reason: it becomes a class name, and `2faModule` is
+ * not a TypeScript identifier. The generated file, the barrel it is appended
+ * to and the `app.ts` it is registered in would all stop compiling, and the
+ * appends mean the overwrite guard cannot undo it. The converters would
+ * rather rename it to `_2faModule`, but a class whose name no longer contains
+ * the name that was asked for — and disagrees with its own file name — is a
+ * worse surprise than a one-line failure the author can act on.
  */
 export declare function assertGeneratableName(name: string, kind?: string): string;
 /**