zudojs-cli 1.0.0 → 1.1.0

package/README.md

@@ -59,11 +59,21 @@ zudojs build
 `zudojs build` and `zudojs doctor` exit with a non-zero status when they fail,
 so they can be used as CI gates.
 
-### Disabling the update check
+### Update check
 
-`zudojs-cli` checks npm for a newer version after a global install. Set
-`ZUDOJS_NO_UPDATE_CHECK=1` to turn it off; it is skipped automatically when
-`CI` is set, when npm is offline, and for non-global installs.
+`zudojs info` asks npm whether a newer `zudojs-cli` exists and prints the
+version if so. Set `ZUDOJS_NO_UPDATE_CHECK=1` to turn it off; it is skipped
+automatically when `CI` is set or npm is offline. Nothing runs at install
+time.
+
+### What a new project contains
+
+`zudojs create` records the project's type, architecture, package manager and
+capabilities in `.zudojs/manifest.json` (machine-managed) and in the `zudojs`
+block of `package.json`. Every follow-up command reads those; no
+`zudojs.config.ts` is written. Framework packages are added as `^1.0.0`
+ranges, and projects created for pnpm carry a `pnpm-workspace.yaml` that
+allows esbuild's build script, which pnpm 10+ would otherwise refuse to run.
 
 ## Commands
 
@@ -71,8 +81,8 @@ so they can be used as CI gates.
 | ---------- | ------------------------------------------------------------------------ |
 | `create`   | Scaffold a new project (backend, frontend, or fullstack)                 |
 | `generate` | Generate files (service, module, command, query, controller, repository) |
-| `add`      | Add feature packages (database, queue, messaging, etc.)                  |
-| `dev`      | Start development servers                                                |
+| `add`      | Add feature packages (database, queue, messaging, etc.); `--service` targets one microservice app |
+| `dev`      | Start development servers through the project's package manager (`pnpm run dev`, …) |
 | `build`    | Build the project with its detected package manager                      |
 | `doctor`   | Run project diagnostics                                                  |
 | `info`     | Show project information                                                 |

package/dist/src/adapters/frontend/frontendAdapter.type.d.ts

@@ -17,6 +17,12 @@ export interface FrontendGenerationContext {
     readonly architecture: "zudojs-standard" | "feature-based" | "minimal" | "framework-default";
     readonly packageManager: "pnpm" | "npm" | "yarn" | "bun";
     readonly features: FrontendFeatures;
+    /**
+     * Record resolved dependencies in package.json instead of installing
+     * them. Set by `zudojs create --no-install`, which the frontend pipeline
+     * used to ignore: it ran the package manager regardless of the flag.
+     */
+    readonly skipInstall?: boolean;
 }
 /**
  * Optional frontend features.

package/dist/src/bin/zudojs.js

@@ -4,12 +4,9 @@
  *
  * @module bin/zudojs
  */
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
 import { createCLI } from "../cliApplication/index.js";
-import { CLI_DEFAULTS } from "../cliConstant/cliConstant.value.js";
 import { createCommand } from "../cliCommand/index.js";
+import { CLI_VERSION, FEATURE_PACKAGES } from "../constants/index.js";
 import { runCreateCommand } from "../commands/create.command.js";
 import { runDevCommand } from "../commands/dev.command.js";
 import { runGenerateCommand } from "../commands/generate.command.js";
@@ -17,32 +14,11 @@ import { runAddCommand } from "../commands/add.command.js";
 import { runBuildCommand } from "../commands/build.command.js";
 import { runDoctorCommand } from "../commands/doctor.command.js";
 import { runInfoCommand } from "../commands/info.command.js";
-/**
- * Reads the CLI's real version from its own package.json at runtime so
- * `zudojs --version` can never drift from the published version.
- */
-function readCliVersion() {
-    let dir = dirname(fileURLToPath(import.meta.url));
-    for (let depth = 0; depth < 6; depth++) {
-        try {
-            const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8"));
-            if (pkg.name === "zudojs-cli" && pkg.version) {
-                return pkg.version;
-            }
-        }
-        catch {
-            // keep walking up
-        }
-        const parent = dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    return CLI_DEFAULTS.VERSION;
-}
 const app = createCLI({
     name: "Zudojs",
-    version: readCliVersion(),
+    // Read from the CLI's own package.json, so `zudojs --version` cannot
+    // drift from the published version.
+    version: CLI_VERSION,
     description: "Command-line interface for the Zudojs framework.",
 });
 app.register(createCommand({
@@ -211,15 +187,15 @@ app.register(createCommand({
     arguments: [
         {
             name: "feature",
-            description: "The feature to add (database, queue, messaging, openapi, observability, security)",
+            description: `The feature to add (${Object.keys(FEATURE_PACKAGES).join(", ")})`,
             required: true,
         },
     ],
     options: [
         {
-            name: "adapter",
-            short: "a",
-            description: "Specific adapter to use",
+            name: "service",
+            short: "s",
+            description: "Add the feature to one app of a microservice project (gateway or a service name)",
             type: "string",
         },
         {

package/dist/src/cliApplication/cliApplication.core.js

@@ -10,8 +10,8 @@ import { CommandNotFoundError } from "../cliError/cliError.command.js";
 import { CLICommandRegistry } from "../cliCommand/cliCommand.registry.js";
 import { executeCommand } from "../cliCommand/cliCommand.factory.js";
 import { CLIParser, resolveCommand } from "../cliParser/index.js";
-import { createDefaultLogger } from "@zudojs/logger";
 import { createCLIWriter } from "./cliApplication.writer.js";
+import { createCLILogger } from "./cliApplication.logger.js";
 import { isHelpRequest, isVersionRequest, printVersion, printHelp, } from "./cliApplication.builtins.js";
 /* -------------------------------------------------------------------------- */
 /* Application                                                                */
@@ -38,7 +38,7 @@ export class ZudojsCLI {
         this.description = options.description ?? CLI_DEFAULTS.DESCRIPTION;
         this.cwd = options.cwd ?? process.cwd();
         this.env = options.env ?? process.env;
-        this.logger = options.logger ?? createDefaultLogger();
+        this.logger = options.logger ?? createCLILogger();
         this.commands = new CLICommandRegistry();
         this.parser = new CLIParser();
         this.writer = createCLIWriter();

package/dist/src/cliApplication/cliApplication.logger.d.ts

@@ -0,0 +1,28 @@
+/**
+ * zudojs-cli — CLI Logger
+ *
+ * A `Logger` whose output is plain terminal text.
+ *
+ * The CLI used `createDefaultLogger()` from `@zudojs/logger`, whose console
+ * transport prints the whole serialised log record. Every line a command
+ * wrote to the user came out as a multi-line object literal with a
+ * timestamp, a level, a logger name and an empty metadata block wrapped
+ * around the message. This logger keeps the `Logger` contract (commands
+ * still receive `context.logger`) and writes one line per call: info to
+ * stdout, warnings and errors to stderr.
+ *
+ * @module cliApplication/logger
+ */
+import { type Logger, type LoggerEntry } from "@zudojs/logger";
+export interface CLILoggerOptions {
+    /** Emit debug and trace lines too. Defaults to `ZUDOJS_DEBUG` being set. */
+    readonly verbose?: boolean;
+    /** Line writers, overridable for tests. */
+    readonly stdout?: (line: string) => void;
+    readonly stderr?: (line: string) => void;
+}
+/** Renders one entry as the single line the user sees. */
+export declare function formatCLILogLine(entry: LoggerEntry): string;
+/** Creates the logger handed to every command as `context.logger`. */
+export declare function createCLILogger(options?: CLILoggerOptions): Logger;
+//# sourceMappingURL=cliApplication.logger.d.ts.map

package/dist/src/cliApplication/cliApplication.logger.js

@@ -0,0 +1,68 @@
+/**
+ * zudojs-cli — CLI Logger
+ *
+ * A `Logger` whose output is plain terminal text.
+ *
+ * The CLI used `createDefaultLogger()` from `@zudojs/logger`, whose console
+ * transport prints the whole serialised log record. Every line a command
+ * wrote to the user came out as a multi-line object literal with a
+ * timestamp, a level, a logger name and an empty metadata block wrapped
+ * around the message. This logger keeps the `Logger` contract (commands
+ * still receive `context.logger`) and writes one line per call: info to
+ * stdout, warnings and errors to stderr.
+ *
+ * @module cliApplication/logger
+ */
+import { createLogger, LoggerLevel, } from "@zudojs/logger";
+/** Renders one entry as the single line the user sees. */
+export function formatCLILogLine(entry) {
+    switch (entry.levelName) {
+        case "fatal":
+        case "error":
+            return `Error: ${entry.message}`;
+        case "warn":
+            return `Warning: ${entry.message}`;
+        case "debug":
+        case "trace":
+            return `[${entry.levelName}] ${entry.message}`;
+        default:
+            return entry.message;
+    }
+}
+/** Creates the logger handed to every command as `context.logger`. */
+export function createCLILogger(options = {}) {
+    const verbose = options.verbose ??
+        (process.env["ZUDOJS_DEBUG"] !== undefined &&
+            process.env["ZUDOJS_DEBUG"] !== "" &&
+            process.env["ZUDOJS_DEBUG"] !== "0");
+    const stdout = options.stdout ?? ((line) => process.stdout.write(`${line}\n`));
+    const stderr = options.stderr ?? ((line) => process.stderr.write(`${line}\n`));
+    return createLogger({
+        name: "zudojs",
+        level: verbose ? LoggerLevel.TRACE : LoggerLevel.INFO,
+        // Writes must complete before a command returns; `process.exit` follows
+        // an error immediately.
+        asynchronous: false,
+        formatter: (entry) => formatCLILogLine(entry),
+        transports: [
+            {
+                name: "cli-stdio",
+                enabled: true,
+                write(entry) {
+                    // The formatter's output arrives as the entry message.
+                    const line = entry.message;
+                    switch (entry.levelName) {
+                        case "fatal":
+                        case "error":
+                        case "warn":
+                            stderr(line);
+                            break;
+                        default:
+                            stdout(line);
+                    }
+                },
+            },
+        ],
+    });
+}
+//# sourceMappingURL=cliApplication.logger.js.map

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

@@ -1,9 +1,7 @@
 /**
  * zudojs-cli — CLI Application
- *
- * Main application class, factory, built-in commands, and signal handling.
  */
 export { ZudojsCLI, createCLI } from "./cliApplication.core.js";
 export { createCLIWriter, registerCLIInterruptHandler, } from "./cliApplication.writer.js";
-export { isHelpRequest, isVersionRequest, printVersion, printHelp, } from "./cliApplication.builtins.js";
+export { createCLILogger, formatCLILogLine, type CLILoggerOptions, } from "./cliApplication.logger.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/cliApplication/index.js

@@ -1,9 +1,7 @@
 /**
  * zudojs-cli — CLI Application
- *
- * Main application class, factory, built-in commands, and signal handling.
  */
 export { ZudojsCLI, createCLI } from "./cliApplication.core.js";
 export { createCLIWriter, registerCLIInterruptHandler, } from "./cliApplication.writer.js";
-export { isHelpRequest, isVersionRequest, printVersion, printHelp, } from "./cliApplication.builtins.js";
+export { createCLILogger, formatCLILogLine, } from "./cliApplication.logger.js";
 //# sourceMappingURL=index.js.map

package/dist/src/cliVersion/cliVersion.update.d.ts

@@ -0,0 +1,38 @@
+/**
+ * zudojs-cli — Update check
+ *
+ * Asks the npm registry whether a newer `zudojs-cli` exists.
+ *
+ * This used to run as a `postinstall` script. npm 11 and pnpm 10 no longer
+ * run install scripts of freshly added packages without explicit approval,
+ * so the check was skipped with a warning on every install and, worse, the
+ * warning made the CLI look broken before it had run once. The check now
+ * runs on demand from `zudojs info`, where a network round-trip is expected.
+ *
+ * @module cliVersion/update
+ */
+export interface UpdateCheckOptions {
+    /** Milliseconds to wait for the registry before giving up. */
+    readonly timeoutMs?: number;
+    readonly registryUrl?: string;
+    readonly packageName?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly fetchImpl?: typeof fetch;
+}
+export interface UpdateCheckResult {
+    readonly current: string;
+    /** The newer published version, or `null` when up to date or unknown. */
+    readonly latest: string | null;
+    /** Why no answer was obtained, when `latest` is `null`. */
+    readonly skipped?: "disabled" | "offline" | "unavailable";
+}
+/**
+ * Whether the update check is turned off for this environment.
+ *
+ * `ZUDOJS_NO_UPDATE_CHECK` disables it explicitly; `CI` and npm's offline
+ * mode disable it implicitly.
+ */
+export declare function isUpdateCheckDisabled(env?: NodeJS.ProcessEnv): boolean;
+/** Looks up the latest published version and compares it with `current`. */
+export declare function checkForNewerVersion(current: string, options?: UpdateCheckOptions): Promise<UpdateCheckResult>;
+//# sourceMappingURL=cliVersion.update.d.ts.map

package/dist/src/cliVersion/cliVersion.update.js

@@ -0,0 +1,63 @@
+/**
+ * zudojs-cli — Update check
+ *
+ * Asks the npm registry whether a newer `zudojs-cli` exists.
+ *
+ * This used to run as a `postinstall` script. npm 11 and pnpm 10 no longer
+ * run install scripts of freshly added packages without explicit approval,
+ * so the check was skipped with a warning on every install and, worse, the
+ * warning made the CLI look broken before it had run once. The check now
+ * runs on demand from `zudojs info`, where a network round-trip is expected.
+ *
+ * @module cliVersion/update
+ */
+import { compareVersions, isValidVersion } from "./cliVersion.core.js";
+/**
+ * Whether the update check is turned off for this environment.
+ *
+ * `ZUDOJS_NO_UPDATE_CHECK` disables it explicitly; `CI` and npm's offline
+ * mode disable it implicitly.
+ */
+export function isUpdateCheckDisabled(env = process.env) {
+    const flag = env["ZUDOJS_NO_UPDATE_CHECK"];
+    if (flag !== undefined && flag !== "" && flag !== "0")
+        return true;
+    if (env["CI"] !== undefined && env["CI"] !== "" && env["CI"] !== "false")
+        return true;
+    if (env["npm_config_offline"] === "true")
+        return true;
+    return false;
+}
+/** Looks up the latest published version and compares it with `current`. */
+export async function checkForNewerVersion(current, options = {}) {
+    if (isUpdateCheckDisabled(options.env)) {
+        return { current, latest: null, skipped: "disabled" };
+    }
+    const packageName = options.packageName ?? "zudojs-cli";
+    const registryUrl = options.registryUrl ?? "https://registry.npmjs.org";
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? 3000);
+    try {
+        const response = await fetchImpl(`${registryUrl}/${encodeURIComponent(packageName)}/latest`, { signal: controller.signal });
+        if (!response.ok) {
+            return { current, latest: null, skipped: "unavailable" };
+        }
+        const data = (await response.json());
+        const latest = typeof data.version === "string" ? data.version : null;
+        if (latest === null ||
+            !isValidVersion(latest) ||
+            !isValidVersion(current) ||
+            compareVersions(latest, current) <= 0) {
+            return { current, latest: null };
+        }
+        return { current, latest };
+    }
+    catch {
+        return { current, latest: null, skipped: "offline" };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=cliVersion.update.js.map

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

@@ -1,7 +1,8 @@
 /**
  * zudojs-cli — CLI Version
  *
- * Semantic version parsing, comparison, and formatting.
+ * Semantic version parsing, comparison, formatting, and the update check.
  */
 export { getCLIVersion, formatCLIVersion, getVersionString, isValidVersion, compareVersions, parseVersion, isCompatibleVersion, type CLIVersionInfo, } from "./cliVersion.core.js";
+export { checkForNewerVersion, isUpdateCheckDisabled, type UpdateCheckOptions, type UpdateCheckResult, } from "./cliVersion.update.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/cliVersion/index.js

@@ -1,7 +1,8 @@
 /**
  * zudojs-cli — CLI Version
  *
- * Semantic version parsing, comparison, and formatting.
+ * Semantic version parsing, comparison, formatting, and the update check.
  */
 export { getCLIVersion, formatCLIVersion, getVersionString, isValidVersion, compareVersions, parseVersion, isCompatibleVersion, } from "./cliVersion.core.js";
+export { checkForNewerVersion, isUpdateCheckDisabled, } from "./cliVersion.update.js";
 //# sourceMappingURL=index.js.map

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

@@ -4,5 +4,34 @@
  * The `zudojs add` command for adding feature packages.
  */
 import type { CLIContext } from "../cliType/cliType.type.js";
+import { type ProjectLayout } from "../resolvers/layout/projectLayout.core.js";
+interface PackageJsonShape {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    zudojs?: Record<string, unknown>;
+}
+/**
+ * Picks the `package.json` files a feature is added to.
+ *
+ * The workspace root used to be the only target. In a fullstack project
+ * that root holds no application code, so `@zudojs/database` landed where
+ * nothing could import it while `apps/api` stayed without it. Features now
+ * go to every backend app (`apps/api`, or the gateway and each service of a
+ * microservice project); `--service <name>` narrows a microservice project
+ * to one app.
+ */
+export declare function selectAddTargets(layout: ProjectLayout, service: string | undefined): string[];
+/**
+ * The version written for a new `@zudojs/*` dependency.
+ *
+ * `workspace:*` was written whenever the project was a workspace. Every
+ * generated fullstack and microservice project is a workspace, and none of
+ * them contains the framework packages, so the next install failed with
+ * "not found in workspace". The protocol is now used only when the target
+ * already links a framework package that way — i.e. inside the Zudojs
+ * monorepo itself.
+ */
+export declare function versionForNewDependency(pkg: PackageJsonShape): string;
 export declare function runAddCommand(context: CLIContext): Promise<void>;
+export {};
 //# sourceMappingURL=add.command.d.ts.map