zudojs-cli 1.2.1 → 2.0.0

package/dist/src/commands/create.command.js

@@ -4,7 +4,7 @@
  * The `zudojs create` command.
  */
 import { join } from "node:path";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import * as p from "@clack/prompts";
 import { generateProject } from "../generators/project/project.generator.js";
@@ -23,9 +23,17 @@ import { promptCapabilities } from "../prompts/capabilities/index.js";
 import { CLIValidationError, CLIGenerationError } from "../errors/index.js";
 import { execCommand, runStreaming } from "../utils/utils.exec.js";
 import { writeFileTree } from "../utils/utils.fileSystem.js";
+import { normalizeName } from "../utils/utils.name.js";
 import { resolveMicroserviceServices } from "../templates/microservice/index.js";
 import { ManifestManager } from "../manifest/manifestManager.core.js";
-import { CLI_VERSION } from "../constants/index.js";
+import { CLI_VERSION, FEATURE_PACKAGES, PACKAGE_MANAGERS, ZUDOJS_PACKAGES_VERSION, } from "../constants/index.js";
+import { registerCLIInterruptHandler } from "../cliApplication/cliApplication.writer.js";
+import { resolveProjectLayout } from "../resolvers/layout/projectLayout.core.js";
+import { CapabilityResolver } from "../resolvers/capability/capabilityResolver.core.js";
+import { CompatibilityValidator } from "../validators/compatibility/compatibilityValidator.core.js";
+import { ProjectValidator } from "../validators/project/projectValidator.core.js";
+import { selectAddTargets } from "./add.command.js";
+import { describeError } from "./commandError.helper.js";
 const VALID_PROJECT_TYPES = ["backend", "frontend", "fullstack"];
 const VALID_ARCHITECTURES = [
     "monolith",
@@ -35,7 +43,6 @@ const VALID_ARCHITECTURES = [
 // No mongodb: there is no adapter for it, and it used to be accepted and
 // scaffolded as PostgreSQL (tooling/CLI-04).
 const VALID_DATABASES = ["postgresql", "mysql", "sqlite"];
-const VALID_PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"];
 const SERVICE_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
 const VALID_FRONTENDS = [
     "none",
@@ -59,6 +66,45 @@ const VALID_FRONTEND_ARCHITECTURES = [
 ];
 const VALID_LANGUAGES = ["typescript", "javascript"];
 const VALID_APIS = ["rest", "graphql", "rpc"];
+/**
+ * Capability ids `--capabilities` accepts.
+ *
+ * Mirrors the options offered by `promptCapabilities`, so the interactive
+ * and non-interactive branches can produce the same project.
+ */
+const VALID_CAPABILITIES = [
+    "cqrs",
+    "events",
+    "messaging",
+    "queue",
+    "observability",
+    "openapi",
+    "database",
+    "security",
+];
+/**
+ * What the non-interactive branch enables when `--capabilities` is absent.
+ * This is what it has always hard-coded; the flag is what makes it
+ * reproducible.
+ */
+const DEFAULT_CAPABILITIES = [
+    "cqrs",
+    "messaging",
+    "observability",
+    "openapi",
+    "database",
+];
+/** Maps a capability selection onto the ScaffoldOptions enable* flags. */
+function capabilityFlags(capabilities) {
+    return {
+        enableCQRS: capabilities.includes("cqrs"),
+        enableMessaging: capabilities.includes("messaging"),
+        enableObservability: capabilities.includes("observability"),
+        enableOpenAPI: capabilities.includes("openapi"),
+        enableDatabase: capabilities.includes("database"),
+        enableQueue: capabilities.includes("queue"),
+    };
+}
 function validateProjectName(name) {
     if (!name || name.trim().length === 0) {
         throw new CLIValidationError("Project name is required.");
@@ -66,8 +112,11 @@ function validateProjectName(name) {
     if (name.includes("..") || name.includes("/") || name.includes("\\")) {
         throw new CLIValidationError("Project name must not contain path separators or '..'.");
     }
-    if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
-        throw new CLIValidationError("Project name must contain only alphanumeric characters, hyphens, and underscores.");
+    // A leading "-" used to be accepted, so `zudojs create -- --weird` made a
+    // directory that `cd` cannot enter and `rm -rf` cannot remove without a
+    // `--` of its own. The first character must be alphanumeric.
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(name)) {
+        throw new CLIValidationError("Project name must start with a letter or digit and contain only alphanumeric characters, hyphens, and underscores.");
     }
 }
 /**
@@ -143,13 +192,24 @@ export async function runCreateCommand(context) {
     // The --services option only applies to microservice architecture; ignore
     // its parser-applied default for other architectures.
     const services = servicesExplicit || architecture === "microservice" ? parsedServices : [];
+    const capabilitiesRaw = context.values.capabilities;
+    const capabilitiesExplicit = hasExplicitFlag(context.args, "--capabilities");
+    const requestedCapabilities = capabilitiesRaw
+        ? capabilitiesRaw
+            .split(",")
+            .map((capability) => capability.trim())
+            .filter(Boolean)
+        : [];
+    for (const capability of requestedCapabilities) {
+        validateChoice(capability, VALID_CAPABILITIES, "capability");
+    }
     if (projectName) {
         validateProjectName(projectName);
     }
     const projectTypeValue = validateChoice(projectType, VALID_PROJECT_TYPES, "project type");
     const architectureValue = validateChoice(architecture, VALID_ARCHITECTURES, "architecture");
     const databaseValue = validateChoice(database, VALID_DATABASES, "database");
-    const packageManagerValue = validateChoice(packageManager, VALID_PACKAGE_MANAGERS, "package manager");
+    const packageManagerValue = validateChoice(packageManager, PACKAGE_MANAGERS, "package manager");
     const frontendValue = validateChoice(frontend, VALID_FRONTENDS, "frontend");
     const frontendArchitectureValue = validateChoice(frontendArchitecture, VALID_FRONTEND_ARCHITECTURES, "frontend architecture");
     const languageValue = validateChoice(language, VALID_LANGUAGES, "language");
@@ -193,6 +253,7 @@ export async function runCreateCommand(context) {
     }
     const isInteractive = process.stdin.isTTY;
     let answers;
+    let selectedCapabilities;
     if (isInteractive) {
         p.intro("Zudojs");
         const name = (await promptProjectName(projectName ?? undefined));
@@ -221,13 +282,11 @@ export async function runCreateCommand(context) {
             ? await promptFrontendArchitecture(explicitOverrides.frontendArchitecture)
             : explicitOverrides.frontendArchitecture;
         const pkgManager = await promptPackageManager(explicitOverrides.packageManager);
-        const capabilities = await promptCapabilities([]);
-        const enableCQRS = capabilities.includes("cqrs");
-        const enableMessaging = capabilities.includes("messaging");
-        const enableObservability = capabilities.includes("observability");
-        const enableOpenAPI = capabilities.includes("openapi");
-        const enableDatabase = capabilities.includes("database");
-        const enableQueue = capabilities.includes("queue");
+        // `--capabilities` seeds the prompt so both branches start from the
+        // same selection.
+        const capabilities = await promptCapabilities(capabilitiesExplicit ? requestedCapabilities : []);
+        selectedCapabilities = capabilities;
+        const flags = capabilityFlags(capabilities);
         const enableDocker = arch === "microservice";
         const confirmed = await promptConfirmation(`Create project "${name}"?`, true);
         if (!confirmed) {
@@ -247,18 +306,18 @@ export async function runCreateCommand(context) {
             language: (explicitOverrides.language ??
                 "typescript"),
             services: interactiveServices,
-            enableCQRS,
-            enableMessaging,
-            enableObservability,
-            enableOpenAPI,
-            enableDatabase,
-            enableQueue,
+            ...flags,
             enableDocker,
             installDeps: !noInstall,
             initGit: !noGit,
         };
     }
     else {
+        // Without --capabilities this is the set the branch has always
+        // hard-coded; with it, the same project the prompts would produce.
+        selectedCapabilities = capabilitiesExplicit
+            ? requestedCapabilities
+            : DEFAULT_CAPABILITIES;
         answers = {
             projectName: projectName ?? "",
             projectType: projectTypeValue,
@@ -273,12 +332,7 @@ export async function runCreateCommand(context) {
             frontendPath: "apps/web",
             language: languageValue,
             services,
-            enableCQRS: true,
-            enableMessaging: true,
-            enableObservability: true,
-            enableOpenAPI: true,
-            enableDatabase: true,
-            enableQueue: false,
+            ...capabilityFlags(selectedCapabilities),
             // Match the interactive branch, which enables Docker for microservices.
             enableDocker: architectureValue === "microservice",
             installDeps: !noInstall,
@@ -299,9 +353,47 @@ export async function runCreateCommand(context) {
             context.logger.warn("--language javascript applies to the frontend (apps/web) only; the backend is generated in TypeScript.");
         }
     }
-    await createProject(answers, context);
+    // `--frontend react --type backend` used to pass validation and then be
+    // discarded without a word, handing the user a backend-only project and
+    // exit 0. Handled like the --language mismatch above.
+    if (hasExplicitFlag(context.args, "--frontend", "-f") &&
+        frontendValue !== "none" &&
+        answers.projectType === "backend") {
+        throw new CLIValidationError(`--frontend ${frontendValue} applies to --type frontend or --type fullstack; a backend project has no frontend. Use --type fullstack to get one.`);
+    }
+    assertCompatibleOptions(answers, context);
+    await createProject(answers, context, selectedCapabilities);
 }
-async function createProject(options, context) {
+/**
+ * Refuses option combinations the generators cannot honour, and reports the
+ * ones that merely need saying.
+ *
+ * The CompatibilityValidator existed, was exported and was tested, but no
+ * command ran it.
+ */
+function assertCompatibleOptions(options, context) {
+    const result = new CompatibilityValidator().validate({
+        projectType: options.projectType ?? "backend",
+        architecture: options.architecture,
+        frontend: options.frontend ?? "none",
+        frontendArchitecture: options.frontendArchitecture ?? "zudojs-standard",
+        packageManager: options.packageManager,
+        database: options.database ?? "postgresql",
+        language: options.language ?? "typescript",
+    });
+    for (const check of result.checks) {
+        if (check.severity === "warning") {
+            context.logger.warn(`${check.option1} + ${check.option2}: ${check.reason}`);
+        }
+    }
+    const errors = result.checks.filter((check) => check.severity === "error");
+    if (errors.length > 0) {
+        throw new CLIValidationError(`Incompatible options:\n${errors
+            .map((check) => `  - ${check.option1} + ${check.option2}: ${check.reason}`)
+            .join("\n")}`);
+    }
+}
+async function createProject(options, context, capabilities) {
     const { projectName, packageManager } = options;
     const targetPath = join(context.cwd, projectName);
     if (existsSync(targetPath)) {
@@ -310,6 +402,29 @@ async function createProject(options, context) {
     const rollback = new RollbackManager();
     rollback.trackDirectory(targetPath);
     const spinner = p.spinner();
+    const installFile = installCommandFor(packageManager);
+    let installFailure = null;
+    // Ctrl-C used to be swallowed: @clack/prompts registers a SIGINT listener
+    // per spinner that only prints "Canceled", and registering any listener
+    // suppresses Node's default termination — so the scaffold ran to
+    // completion and exited 0. This removes the half-written project and
+    // exits with the interrupted status.
+    const unregisterInterrupt = registerCLIInterruptHandler(async () => {
+        try {
+            spinner.stop("Interrupted");
+        }
+        catch {
+            // The spinner may not be running; the rollback is what matters.
+        }
+        const result = await rollback.rollback();
+        if (result.failures.length > 0) {
+            p.cancel(`Cancelled, but ${result.failures
+                .map((failure) => `${failure.path} (${failure.reason})`)
+                .join(", ")} could not be removed — delete it by hand.`);
+            return;
+        }
+        p.cancel(`Cancelled. Removed ${targetPath}.`);
+    });
     try {
         spinner.start("Creating project structure");
         await mkdir(targetPath, { recursive: true });
@@ -333,16 +448,9 @@ async function createProject(options, context) {
             const result = await generateProject(options, targetPath);
             spinner.stop(`Backend project generated (${result.filesCreated.length} files)`);
         }
-        await writeProjectManifest(options, targetPath);
+        await writeProjectManifest(options, targetPath, capabilities);
+        await applyCapabilityPackages(targetPath, capabilities, context);
         if (options.installDeps) {
-            spinner.start("Installing dependencies");
-            const installFile = packageManager === "pnpm"
-                ? "pnpm"
-                : packageManager === "yarn"
-                    ? "yarn"
-                    : packageManager === "bun"
-                        ? "bun"
-                        : "npm";
             try {
                 // Streamed with no timeout: installs can be slow and their output
                 // should reach the user.
@@ -352,11 +460,22 @@ async function createProject(options, context) {
             }
             catch (error) {
                 // The project is complete without its node_modules; say what
-                // failed and how to retry instead of a bare "skipped".
+                // failed and how to retry instead of a bare "skipped". The command
+                // still exits non-zero — `zudojs add` fails on the same error, and
+                // a CI job must not go green with no node_modules.
                 const reason = error instanceof Error ? error.message : String(error);
+                installFailure = reason;
                 p.log.warn(`Dependency installation failed: ${reason}\nRun "${installFile} install" inside ${projectName} to retry.`);
             }
         }
+        spinner.start("Validating the generated project");
+        const problems = await collectProjectProblems(targetPath, options, installFailure === null);
+        spinner.stop(problems.length === 0
+            ? "Project validated"
+            : `Project validated with ${problems.length} warning(s)`);
+        for (const problem of problems) {
+            p.log.warn(`Project check: ${problem}`);
+        }
         if (options.initGit) {
             spinner.start("Initializing git repository");
             try {
@@ -375,20 +494,127 @@ async function createProject(options, context) {
                     ? "bun run dev"
                     : "pnpm run dev";
         p.note(`cd ${projectName}\n${devCmd}`, "Next steps");
-        p.outro("Project created successfully.");
+        p.outro(installFailure === null
+            ? "Project created successfully."
+            : "Project created, but dependencies were NOT installed.");
     }
     catch (error) {
-        await rollback.rollback();
-        const message = error instanceof Error ? error.message : String(error);
-        p.cancel(`Failed to create project: ${message}`);
-        throw new CLIGenerationError(`Failed to create project "${projectName}"`, error);
+        const result = await rollback.rollback();
+        // The cause chain is rendered here: generators throw
+        // CLIGenerationError("Failed to write project files:", cause) and the
+        // cause was the only thing that said what went wrong.
+        const message = describeError(error);
+        const leftBehind = result.failures.length > 0
+            ? `\nCould not remove ${result.failures
+                .map((failure) => `${failure.path} (${failure.reason})`)
+                .join(", ")} — delete it by hand before retrying.`
+            : "";
+        p.cancel(`Failed to create project: ${message}${leftBehind}`);
+        throw new CLIGenerationError(`Failed to create project "${projectName}": ${message}${leftBehind}`, error);
+    }
+    finally {
+        unregisterInterrupt();
+    }
+    if (installFailure !== null) {
+        // Thrown outside the try so the finished project is not rolled back.
+        throw new CLIGenerationError(`Project "${projectName}" was created at ${targetPath}, but dependency installation failed: ${installFailure}. Run "${installFile} install" inside ${projectName} to retry.`);
+    }
+}
+/** The binary that installs dependencies for a package manager. */
+function installCommandFor(packageManager) {
+    switch (packageManager) {
+        case "pnpm":
+            return "pnpm";
+        case "yarn":
+            return "yarn";
+        case "bun":
+            return "bun";
+        default:
+            return "npm";
     }
 }
+/**
+ * Adds the packages behind capabilities the templates do not wire
+ * themselves.
+ *
+ * The capability prompt offers `events` and `security`, but only six of its
+ * eight options reached ScaffoldOptions, so ticking **Security** produced
+ * no dependency, no manifest capability and no message.
+ */
+async function applyCapabilityPackages(targetPath, capabilities, context) {
+    if (capabilities.length === 0)
+        return;
+    const layout = resolveProjectLayout(targetPath);
+    if (!layout || layout.backendDirs.length === 0)
+        return;
+    const required = new Set();
+    for (const capability of capabilities) {
+        for (const name of FEATURE_PACKAGES[capability] ?? []) {
+            required.add(name);
+        }
+    }
+    if (required.size === 0)
+        return;
+    const added = new Set();
+    for (const pkgPath of selectAddTargets(layout, undefined)) {
+        if (!existsSync(pkgPath))
+            continue;
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        pkg.dependencies ??= {};
+        let changed = false;
+        for (const name of required) {
+            if (!(name in pkg.dependencies)) {
+                pkg.dependencies[name] = ZUDOJS_PACKAGES_VERSION;
+                added.add(name);
+                changed = true;
+            }
+        }
+        const block = (pkg.zudojs ??= {});
+        const features = new Set(Array.isArray(block.features)
+            ? block.features.filter((f) => typeof f === "string")
+            : []);
+        for (const capability of capabilities) {
+            if (!features.has(capability)) {
+                features.add(capability);
+                changed = true;
+            }
+        }
+        block.features = [...features];
+        if (changed) {
+            writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+        }
+    }
+    if (added.size > 0) {
+        context.logger.info(`Capability packages added: ${[...added].join(", ")}`);
+    }
+    const resolution = new CapabilityResolver().resolve(capabilities);
+    if (resolution.dependencies.length > 0) {
+        context.logger.info(`Capabilities build on: ${resolution.dependencies.join(", ")}`);
+    }
+}
+/**
+ * Checks the project that was just written and returns anything wrong with
+ * it. Never fatal: the files exist and the user can look at them.
+ */
+async function collectProjectProblems(targetPath, options, installed) {
+    const layout = resolveProjectLayout(targetPath);
+    const appDir = layout?.backendDirs[0];
+    // Backend apps only: a Flutter or React Native app has no tsconfig.json
+    // and no src/, and would fail every check for no reason.
+    if (appDir === undefined)
+        return [];
+    const dependenciesInstalled = installed && options.installDeps === true;
+    const result = await new ProjectValidator().validate(appDir, {
+        expectInstalled: dependenciesInstalled,
+        typecheck: dependenciesInstalled,
+    });
+    return result.errors;
+}
 /**
  * Writes the machine-managed .zudojs/manifest.json so follow-up commands
  * (`zudojs dev`, `generate`, `add`) recognize the project immediately.
  */
-async function writeProjectManifest(options, targetPath) {
+async function writeProjectManifest(options, targetPath, selected = []) {
     const capabilities = [];
     if (options.enableCQRS)
         capabilities.push("cqrs");
@@ -402,12 +628,24 @@ async function writeProjectManifest(options, targetPath) {
         capabilities.push("database");
     if (options.enableQueue)
         capabilities.push("queue");
+    // Capabilities with no ScaffoldOptions flag of their own (events,
+    // security) were selected and then dropped on the floor.
+    for (const capability of selected) {
+        if (!capabilities.includes(capability))
+            capabilities.push(capability);
+    }
     // Record the services actually generated, not the raw request: the
-    // template drops reserved names (gateway) and duplicates, and substitutes
-    // its own defaults for an empty list.
+    // microservice template drops reserved names (gateway) and duplicates, and
+    // the modular-monolith template normalizes each name into a directory
+    // segment. A modular monolith's modules were previously not recorded at
+    // all, so later commands had no way to know which modules existed.
     const services = options.architecture === "microservice"
         ? resolveMicroserviceServices(options.services)
-        : undefined;
+        : options.architecture === "modular-monolith"
+            ? options.services
+                .map((module) => normalizeName(module))
+                .filter((module) => module.length > 0)
+            : undefined;
     const hasFrontend = options.frontend !== undefined && options.frontend !== "none";
     const hasBackend = options.projectType !== "frontend";
     await new ManifestManager(targetPath).create({

package/dist/src/commands/doctor.command.d.ts

@@ -22,5 +22,13 @@ export interface DoctorCheck {
  * without going through the logger.
  */
 export declare function runDoctorChecks(cwd: string): DoctorCheck[];
+/**
+ * Environment checks: Node.js, Git and the project's own package manager.
+ *
+ * Delegated to the EnvironmentValidator, which existed and was exported
+ * but was called from nowhere while `doctor` reimplemented a subset of it
+ * inline.
+ */
+export declare function runEnvironmentChecks(cwd: string): Promise<DoctorCheck[]>;
 export declare function runDoctorCommand(context: CLIContext): Promise<void>;
 //# sourceMappingURL=doctor.command.d.ts.map

package/dist/src/commands/doctor.command.js

@@ -8,6 +8,7 @@ import { join, relative } from "node:path";
 import { CLIValidationError } from "../errors/index.js";
 import { FEATURE_PACKAGES } from "../constants/index.js";
 import { resolveProjectLayout, } from "../resolvers/layout/projectLayout.core.js";
+import { EnvironmentValidator, } from "../validators/environment/environmentValidator.core.js";
 /**
  * Runs every diagnostic for the project at `cwd`.
  *
@@ -16,15 +17,39 @@ import { resolveProjectLayout, } from "../resolvers/layout/projectLayout.core.js
  */
 export function runDoctorChecks(cwd) {
     const layout = resolveProjectLayout(cwd);
-    const checks = [checkNodeVersion(), checkProject(layout)];
+    const checks = [checkProject(layout)];
     if (!layout) {
         return checks;
     }
     checks.push(checkPackageManager(layout), checkInstalled(layout), checkTypeScriptConfig(layout), checkDependencies(layout), checkFeatures(layout));
     return checks;
 }
+/**
+ * Environment checks: Node.js, Git and the project's own package manager.
+ *
+ * Delegated to the EnvironmentValidator, which existed and was exported
+ * but was called from nowhere while `doctor` reimplemented a subset of it
+ * inline.
+ */
+export async function runEnvironmentChecks(cwd) {
+    const layout = resolveProjectLayout(cwd);
+    const result = await new EnvironmentValidator().validate(layout?.projectType ?? "backend", layout?.packageManager);
+    return result.checks.map((check) => check.name === "Node.js"
+        ? checkNodeVersion(check)
+        : {
+            name: check.name === "Git" ? "Git" : `Package manager (${check.name})`,
+            severity: "warning",
+            passed: check.installed,
+            message: check.installed
+                ? `${check.version ?? "installed"}`
+                : `${check.name} is not installed or not on PATH`,
+        });
+}
 export async function runDoctorCommand(context) {
-    const checks = runDoctorChecks(context.cwd);
+    const checks = [
+        ...(await runEnvironmentChecks(context.cwd)),
+        ...runDoctorChecks(context.cwd),
+    ];
     const warnings = [];
     const errors = [];
     context.logger.info("Zudojs Doctor - Project Diagnostics");
@@ -63,10 +88,18 @@ export async function runDoctorCommand(context) {
     context.logger.info("");
     context.logger.info("All checks passed!");
 }
-function checkNodeVersion() {
-    const version = process.version;
+function checkNodeVersion(check) {
+    if (!check.installed) {
+        return {
+            name: "Node.js version",
+            severity: "error",
+            passed: false,
+            message: "Node.js is not installed or not on PATH",
+        };
+    }
+    const version = check.version ?? process.version;
     const major = Number.parseInt(version.replace("v", "").split(".")[0], 10);
-    const passed = major >= 24;
+    const passed = Number.isFinite(major) && major >= 24;
     return {
         name: "Node.js version",
         severity: "error",